No edit summary |
(feedback from pbokoc) |
||
Line 30: | Line 30: | ||
|bridgehead||A free-floating heading|| | |bridgehead||A free-floating heading|| | ||
|- | |- | ||
|chapter||A chapter, as of a book|| | |chapter||A chapter, as of a book|| yes, but ADoc has its own structural elements anyway (same for chapter, formalpara, section and part) | ||
|- | |- | ||
|citation||An inline bibliographic reference to another published work|| | |citation||An inline bibliographic reference to another published work|| | ||
|- | |- | ||
|citetitle||The title of a cited work|| | |citetitle||The title of a cited work|| yes for automated tests (if we can differentiate between citing another article/topic/book in our docs vs. citing something external) | ||
|- | |- | ||
|colspec||Specifications for a column in a table|| | |colspec||Specifications for a column in a table|| | ||
Line 50: | Line 50: | ||
|email||An email address|| | |email||An email address|| | ||
|- | |- | ||
|emphasis||Emphasized text|| | |emphasis||Emphasized text|| that's definitely useful | ||
|- | |- | ||
|entry||A cell in a table|| | |entry||A cell in a table|| | ||
Line 64: | Line 64: | ||
|firstterm||The first occurrence of a term|| | |firstterm||The first occurrence of a term|| | ||
|- | |- | ||
|footnote||A footnote|| | |footnote||A footnote|| this tends to be useful in tables sometimes, not so much in text | ||
|- | |- | ||
|formalpara||A paragraph with a title|| | |formalpara||A paragraph with a title|| yes, but ADoc has its own structural elements anyway (same for chapter, formalpara, section and part) | ||
|- | |- | ||
|guibutton||The text on a button in a GUI||yes for consistent formatting? | |guibutton||The text on a button in a GUI||yes for consistent formatting? | ||
Line 76: | Line 76: | ||
|guimenuitem||The name of a terminal menu item in a GUI||yes for consistent formatting? | |guimenuitem||The name of a terminal menu item in a GUI||yes for consistent formatting? | ||
|- | |- | ||
|guisubmenu||The name of a submenu in a GUI|| | |guisubmenu||The name of a submenu in a GUI|| I think we could do with just one tag for any GUI element, no need to distinguish buttons from menus imo | ||
|- | |- | ||
|imagedata||Pointer to external image data|| | |imagedata||Pointer to external image data|| | ||
Line 82: | Line 82: | ||
|imageobject||A wrapper for image data and its associated meta-information|| | |imageobject||A wrapper for image data and its associated meta-information|| | ||
|- | |- | ||
|important||An admonition set off from the text|| | |important||An admonition set off from the text|| yes, definitely | ||
|- | |- | ||
|index||An index|| | |index||An index|| | ||
Line 88: | Line 88: | ||
|inlinemediaobject||An inline media object (video, audio, image, and so on)|| | |inlinemediaobject||An inline media object (video, audio, image, and so on)|| | ||
|- | |- | ||
|itemizedlist||A list in which each entry is marked with a bullet or other dingbat|| | |itemizedlist||A list in which each entry is marked with a bullet or other dingbat|| definitely useful | ||
|- | |- | ||
|keycap||The text printed on a key on a keyboard||yes for consistent formatting? | |keycap||The text printed on a key on a keyboard||yes for consistent formatting? | ||
Line 100: | Line 100: | ||
|listitem||A wrapper for the elements of a list item|| | |listitem||A wrapper for the elements of a list item|| | ||
|- | |- | ||
|literal||Inline text that is some literal value|| | |literal||Inline text that is some literal value|| yes, useful | ||
|- | |- | ||
|mediaobject||A displayed media object (video, audio, image, etc.)|| | |mediaobject||A displayed media object (video, audio, image, etc.)|| | ||
Line 106: | Line 106: | ||
|member||An element of a simple list|| | |member||An element of a simple list|| | ||
|- | |- | ||
|note||A message set off from the text|| | |note||A message set off from the text|| yes, definitely | ||
|- | |- | ||
|option||An option for a software command|| | |option||An option for a software command|| this could be useful to differentiate commands from options in automated tests, but we could probably work around that by just testing up to the first space in a command and ignoring the rest | ||
|- | |- | ||
|orderedlist||A list in which each entry is marked with a sequentially incremented label|| | |orderedlist||A list in which each entry is marked with a sequentially incremented label|| yes, useful | ||
|- | |- | ||
|package|| | |package|| A name of a software package (e.g. a RPM) || useful for automated tests | ||
|- | |- | ||
|para||A paragraph|| | |para||A paragraph|| | ||
|- | |- | ||
|parameter||A value or a symbolic reference to a value|| | |parameter||A value or a symbolic reference to a value|| might be useful, but then again it tends to be used interchangeably with option so maybe not | ||
|- | |- | ||
|part||A division in a book|| | |part||A division in a book|| yes, but ADoc has its own structural elements anyway (same for chapter, formalpara, section and part) | ||
|- | |- | ||
|partintro||An introduction to the contents of a part|| | |partintro||An introduction to the contents of a part|| | ||
Line 126: | Line 126: | ||
|preface||Introductory matter preceding the first chapter of a book|| | |preface||Introductory matter preceding the first chapter of a book|| | ||
|- | |- | ||
|procedure||A list of operations to be performed in a well-defined sequence|| | |procedure||A list of operations to be performed in a well-defined sequence|| might be useful, but we can probably do the same with orderedlists | ||
|- | |- | ||
|productname||The formal name of a product|| | |productname||The formal name of a product|| useful for automated testing | ||
|- | |- | ||
|productnumber||A number assigned to a product|| | |productnumber||A number assigned to a product|| useful for automated testing | ||
|- | |- | ||
|programlisting||A literal listing of all or part of a program|| | |programlisting||A literal listing of all or part of a program|| definitely useful for e.g. code examples | ||
|- | |- | ||
|prompt||A character or string indicating the start of an input field in a computer display|| | |prompt||A character or string indicating the start of an input field in a computer display|| | ||
Line 140: | Line 140: | ||
|quote||An inline quotation|| | |quote||An inline quotation|| | ||
|- | |- | ||
|remark||??|| | |remark||??|| this is useful for inserting notes inside built content (as opposed to source comments) when you need to get feedback and don't want to just give people the source since it's hard to read. However ADoc sources are significantly more readable than that so sending the source with inline comments could work as well. | ||
|- | |- | ||
|replaceable||Content that may or must be replaced by the user|| | |replaceable||Content that may or must be replaced by the user|| definitely useful | ||
|- | |- | ||
|revdescription|| | |revdescription||A description of changes in a revision|| | ||
|- | |- | ||
|revhistory||A history of the revisions to a document|| | |revhistory||A history of the revisions to a document|| we might want to keep this plus revision so we can test that a publisher has updated the revhistory when republishing - it's probably good to let people know when the last change to a document happened. However that sounds like it could be automated during the publishing process. | ||
|- | |- | ||
|revision||An entry | |revision||An entry encapsulating a single revision in the history of the revisions to a document|| see above | ||
|- | |- | ||
|revnumber||A document revision number|| | |revnumber||A document revision number|| | ||
Line 154: | Line 154: | ||
|row||A row in a table|| | |row||A row in a table|| | ||
|- | |- | ||
|screen||Text that a user sees or might see on a computer screen|| | |screen||Text that a user sees or might see on a computer screen|| useful for examples, especially when you're giving an example of a command plus its output | ||
|- | |- | ||
|section||A recursive section|| | |section||A recursive section||yes, but ADoc has its own structural elements anyway (same for chapter, formalpara, section and part) | ||
|- | |- | ||
|simpara||A paragraph that contains only text and inline markup, no block elements|| | |simpara||A paragraph that contains only text and inline markup, no block elements|| | ||
Line 176: | Line 176: | ||
|surname||A family name; in western cultures the last name|| | |surname||A family name; in western cultures the last name|| | ||
|- | |- | ||
|systemitem||A system-related item or term|| | |systemitem||A system-related item or term|| definitely useful for stuff like hostnames/IPs, device names, user and group names, ... | ||
|- | |- | ||
|table||A formal table in a document|| | |table||A formal table in a document|| | ||
Line 190: | Line 190: | ||
|thead||A table header consisting of one or more rows|| | |thead||A table header consisting of one or more rows|| | ||
|- | |- | ||
|title||The text of the title of a section of a document or of a formal block-level element|| | |title||The text of the title of a section of a document or of a formal block-level element|| ADoc supports that anyway | ||
|- | |- | ||
|ulink||A link that addresses its target by means of a URL (Uniform Resource Locator)|| | |ulink||A link that addresses its target by means of a URL (Uniform Resource Locator)||ADoc supports that anyway | ||
|- | |- | ||
|userinput||Data entered by the user|| | |userinput||Data entered by the user|| | ||
Line 200: | Line 200: | ||
|varlistentry||A wrapper for a set of terms and the associated description in a variable list|| | |varlistentry||A wrapper for a set of terms and the associated description in a variable list|| | ||
|- | |- | ||
|warning||An admonition set off from the text|| | |warning||An admonition set off from the text|| yes, definitely | ||
|- | |- | ||
|wordasword||A word meant specifically as a word and not representing anything else|| | |wordasword||A word meant specifically as a word and not representing anything else|| | ||
|- | |- | ||
|xref||A cross reference to another part of the document|| | |xref||A cross reference to another part of the document|| ADoc supports that anyway (or at least I hope so) | ||
|- | |- | ||
|} | |} |
Revision as of 15:07, 14 September 2016
Below is a list of the 97 DocBook XML tags found in the Installation Guide. AsciiDoc does not have a lot of semantic markup. There is a possibility of creating some small semantic elements to use within AsciiDoc to provide three benefits:
1. Meaning for translators doing i18n so they can decide on whether to localize a term or not
2. Consistency of formatting. No one has to memorize that element A is italic or element B is bold
3. Automated testing with something like emender
down the road.
This table is not complete and contains ideas. Please add justifications to keep a tag. Tags that shouldn't be kept, leave blank. Disagree? add a note in the table.
DocBook Tag | Description | Keep? (blank == no) |
---|---|---|
abstract | A summary | |
acronym | An often pronounceable word made from the initial (or selected) letters of a name or phrase | only if needed by i18n |
appendix | An appendix in a Book or Article | |
application | The name of a software program | yes for automated tests |
author | The name of an individual author | |
authorgroup | Wrapper for author information when a document has multiple authors or collabarators | |
book | A book | |
bookinfo | Meta-information for a Book | |
bridgehead | A free-floating heading | |
chapter | A chapter, as of a book | yes, but ADoc has its own structural elements anyway (same for chapter, formalpara, section and part) |
citation | An inline bibliographic reference to another published work | |
citetitle | The title of a cited work | yes for automated tests (if we can differentiate between citing another article/topic/book in our docs vs. citing something external) |
colspec | Specifications for a column in a table | |
command | The name of an executable program or other software command | yes for automated tests |
computeroutput | Data, generally text, displayed or presented by a computer | yes for automated tests |
corpauthor | A corporate author, as opposed to an individual | |
date | The date of publication or revision of a document | |
edition | The name or number of an edition of a document | |
An email address | ||
emphasis | Emphasized text | that's definitely useful |
entry | A cell in a table | |
example | A formal example, with a title | yes for consistent formatting? |
figure | A formal figure, generally an illustration, with a title | |
filename | The name of a file | yes for consistent formatting? |
firstname | The first name of a person | |
firstterm | The first occurrence of a term | |
footnote | A footnote | this tends to be useful in tables sometimes, not so much in text |
formalpara | A paragraph with a title | yes, but ADoc has its own structural elements anyway (same for chapter, formalpara, section and part) |
guibutton | The text on a button in a GUI | yes for consistent formatting? |
guilabel | The text of a label in a GUI | yes for consistent formatting? |
guimenu | The name of a menu in a GUI | yes for consistent formatting? |
guimenuitem | The name of a terminal menu item in a GUI | yes for consistent formatting? |
guisubmenu | The name of a submenu in a GUI | I think we could do with just one tag for any GUI element, no need to distinguish buttons from menus imo |
imagedata | Pointer to external image data | |
imageobject | A wrapper for image data and its associated meta-information | |
important | An admonition set off from the text | yes, definitely |
index | An index | |
inlinemediaobject | An inline media object (video, audio, image, and so on) | |
itemizedlist | A list in which each entry is marked with a bullet or other dingbat | definitely useful |
keycap | The text printed on a key on a keyboard | yes for consistent formatting? |
keycombo | A combination of input actions | yes for consistent formatting? |
keyword | One of a set of keywords describing the content of a document | |
keywordset | A set of keywords describing the content of a document | |
listitem | A wrapper for the elements of a list item | |
literal | Inline text that is some literal value | yes, useful |
mediaobject | A displayed media object (video, audio, image, etc.) | |
member | An element of a simple list | |
note | A message set off from the text | yes, definitely |
option | An option for a software command | this could be useful to differentiate commands from options in automated tests, but we could probably work around that by just testing up to the first space in a command and ignoring the rest |
orderedlist | A list in which each entry is marked with a sequentially incremented label | yes, useful |
package | A name of a software package (e.g. a RPM) | useful for automated tests |
para | A paragraph | |
parameter | A value or a symbolic reference to a value | might be useful, but then again it tends to be used interchangeably with option so maybe not |
part | A division in a book | yes, but ADoc has its own structural elements anyway (same for chapter, formalpara, section and part) |
partintro | An introduction to the contents of a part | |
phrase | A span of text | |
preface | Introductory matter preceding the first chapter of a book | |
procedure | A list of operations to be performed in a well-defined sequence | might be useful, but we can probably do the same with orderedlists |
productname | The formal name of a product | useful for automated testing |
productnumber | A number assigned to a product | useful for automated testing |
programlisting | A literal listing of all or part of a program | definitely useful for e.g. code examples |
prompt | A character or string indicating the start of an input field in a computer display | |
pubsnumber | A number assigned to a publication other than an ISBN or ISSN or inventory part number | |
quote | An inline quotation | |
remark | ?? | this is useful for inserting notes inside built content (as opposed to source comments) when you need to get feedback and don't want to just give people the source since it's hard to read. However ADoc sources are significantly more readable than that so sending the source with inline comments could work as well. |
replaceable | Content that may or must be replaced by the user | definitely useful |
revdescription | A description of changes in a revision | |
revhistory | A history of the revisions to a document | we might want to keep this plus revision so we can test that a publisher has updated the revhistory when republishing - it's probably good to let people know when the last change to a document happened. However that sounds like it could be automated during the publishing process. |
revision | An entry encapsulating a single revision in the history of the revisions to a document | see above |
revnumber | A document revision number | |
row | A row in a table | |
screen | Text that a user sees or might see on a computer screen | useful for examples, especially when you're giving an example of a command plus its output |
section | A recursive section | yes, but ADoc has its own structural elements anyway (same for chapter, formalpara, section and part) |
simpara | A paragraph that contains only text and inline markup, no block elements | |
simplelist | An undecorated list of single words or short phrases | |
step | A unit of action in a procedure | |
subject | One of a group of terms describing the subject matter of a document | |
subjectset | A set of terms describing the subject matter of a document | |
subjectterm | A term in a group of terms describing the subject matter of a document | |
substeps | A wrapper for steps that occur within steps in a procedure | |
subtitle | The subtitle of a document | |
surname | A family name; in western cultures the last name | |
systemitem | A system-related item or term | definitely useful for stuff like hostnames/IPs, device names, user and group names, ... |
table | A formal table in a document | |
tbody | A wrapper for the rows of a table or informal table | |
term | The word or phrase being defined or described in a variable list | |
textobject | A wrapper for a text description of an object and its associated meta-information | |
tgroup | A wrapper for the main content of a table, or part of a table | |
thead | A table header consisting of one or more rows | |
title | The text of the title of a section of a document or of a formal block-level element | ADoc supports that anyway |
ulink | A link that addresses its target by means of a URL (Uniform Resource Locator) | ADoc supports that anyway |
userinput | Data entered by the user | |
variablelist | A list in which each entry is composed of a set of one or more terms and an associated description | |
varlistentry | A wrapper for a set of terms and the associated description in a variable list | |
warning | An admonition set off from the text | yes, definitely |
wordasword | A word meant specifically as a word and not representing anything else | |
xref | A cross reference to another part of the document | ADoc supports that anyway (or at least I hope so) |