From Fedora Project Wiki

m
(Split table and combined some elements)
Line 7: Line 7:
 
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.
 
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.
  
 
+
Note: I have split the table into three parts to make it easier to read.  If you modify an entry, make sure you move it to the correct table!
 +
Tags Suggested to be kept:
 
{||
 
{||
 
|-
 
|-
!DocBook Tag!!Description!!Keep? (blank == no)
+
!DocBook Tag!!Description!!Reason for Keeping
 +
|-
 +
|acronym||An often pronounceable word made from the initial (or selected) letters of a name or phrase|| only if needed by i18n
 +
|-
 +
|application||The name of a software program|| yes for automated tests
 +
|-
 +
|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)
 +
|-
 +
|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
 +
|-
 +
|example||A formal example, with a title||yes for consistent formatting?
 +
|-
 +
|filename||The name of a file||yes for consistent formatting?
 +
|-
 +
|guibutton, guilabel, guimenuitem, guimenu, guisubmenu ||Various GUI Elements|| I think we could do with just one tag for any GUI element, no need to distinguish buttons from menus imo
 
|-
 
|-
|abstract||A summary||
+
|keycap, keycombo||various key related elements||yes for consistent formatting?
 
|-
 
|-
|acronym||An often pronounceable word made from the initial (or selected) letters of a name or phrase|| only if needed by i18n
+
|literal||Inline text that is some literal value|| yes, useful
 
|-
 
|-
|appendix||An appendix in a Book or Article||
+
|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
 
|-
 
|-
|application||The name of a software program|| yes for automated tests
+
|package|| A name of a software package (e.g. a RPM) || useful for automated tests
 
|-
 
|-
|author||The name of an individual author||
+
|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
 
|-
 
|-
|authorgroup||Wrapper for author information when a document has multiple authors or collabarators||
+
|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
 
|-
 
|-
|book||A book||
+
|productname||The formal name of a product|| useful for automated testing
 
|-
 
|-
|bookinfo||Meta-information for a Book||
+
|productnumber||A number assigned to a product|| useful for automated testing
 
|-
 
|-
|bridgehead||A free-floating heading||
+
|programlisting||A literal listing of all or part of a program|| definitely useful for e.g. code examples
 
|-
 
|-
|chapter||A chapter, as of a book|| yes, but ADoc has its own structural elements anyway (same for chapter, formalpara, section and part)
+
|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.
 
|-
 
|-
|citation||An inline bibliographic reference to another published work||
+
|replaceable||Content that may or must be replaced by the user|| definitely useful
 
|-
 
|-
|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)
+
|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.
 
|-
 
|-
|colspec||Specifications for a column in a table|| sure, but ADoc handles tables its own way anyway
+
|revision||An entry encapsulating a single revision in the history of the revisions to a document|| see above
 
|-
 
|-
|command||The name of an executable program or other software command|| yes for automated tests
+
|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
 
|-
 
|-
|computeroutput||Data, generally text, displayed or presented by a computer||yes for automated tests
+
|systemitem||A system-related item or term|| definitely useful for stuff like hostnames/IPs, device names, user and group names, ...
 
|-
 
|-
|corpauthor||A corporate author, as opposed to an individual||
+
|}
 +
 
 +
Tags desired, but already handled by AsciiDoc:
 +
{||
 
|-
 
|-
|date||The date of publication or revision of a document||
+
!DocBook Tag!!Description!!Reason for Keeping
 
|-
 
|-
|edition||The name or number of an edition of a document||
+
|chapter||A chapter, as of a book|| yes, but ADoc has its own structural elements anyway (same for chapter, formalpara, section and part)
 
|-
 
|-
|email||An email address||
+
|colspec||Specifications for a column in a table|| sure, but ADoc handles tables its own way anyway
 
|-
 
|-
 
|emphasis||Emphasized text|| that's definitely useful
 
|emphasis||Emphasized text|| that's definitely useful
Line 54: Line 74:
 
|entry||A cell in a table|| sure, but ADoc handles tables its own way anyway
 
|entry||A cell in a table|| sure, but ADoc handles tables its own way anyway
 
|-
 
|-
|example||A formal example, with a title||yes for consistent formatting?
+
|footnote||A footnote|| this tends to be useful in tables sometimes, not so much in text
 
|-
 
|-
|figure||A formal figure, generally an illustration, 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)
 
|-
 
|-
|filename||The name of a file||yes for consistent formatting?
+
|important||An admonition set off from the text|| yes, definitely
 
|-
 
|-
|firstname||The first name of a person||
+
|itemizedlist||A list in which each entry is marked with a bullet or other dingbat|| definitely useful
 
|-
 
|-
|firstterm||The first occurrence of a term||
+
|note||A message set off from the text|| yes, definitely
 
|-
 
|-
|footnote||A footnote|| this tends to be useful in tables sometimes, not so much in text
+
|orderedlist||A list in which each entry is marked with a sequentially incremented label|| yes, useful
 
|-
 
|-
|formalpara||A paragraph with a title|| yes, but ADoc has its own structural elements anyway (same for chapter, formalpara, section and part)
+
|part||A division in a book|| 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?
+
|row||A row in a table||sure, but ADoc handles tables its own way anyway
 
|-
 
|-
|guilabel||The text of a label in a GUI||yes for consistent formatting?
+
|section||A recursive section||yes, but ADoc has its own structural elements anyway (same for chapter, formalpara, section and part)
 
|-
 
|-
|guimenu||The name of a menu in a GUI||yes for consistent formatting?
+
|table||A formal table in a document||sure, but ADoc handles tables its own way anyway
 
|-
 
|-
|guimenuitem||The name of a terminal menu item in a GUI||yes for consistent formatting?
+
|tbody||A wrapper for the rows of a table or informal table||sure, but ADoc handles tables its own way anyway
 
|-
 
|-
|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
+
|tgroup||A wrapper for the main content of a table, or part of a table||sure, but ADoc handles tables its own way anyway
 
|-
 
|-
|imagedata||Pointer to external image data||
+
|thead||A table header consisting of one or more rows||sure, but ADoc handles tables its own way anyway
 
|-
 
|-
|imageobject||A wrapper for image data and its associated meta-information||
+
|title||The text of the title of a section of a document or of a formal block-level element|| ADoc supports that anyway
 
|-
 
|-
|important||An admonition set off from the text|| yes, definitely
+
|ulink||A link that addresses its target by means of a URL (Uniform Resource Locator)||ADoc supports that anyway
 
|-
 
|-
|index||An index||
+
|warning||An admonition set off from the text|| yes, definitely
 
|-
 
|-
|inlinemediaobject||An inline media object (video, audio, image, and so on)||
+
|xref||A cross reference to another part of the document|| ADoc supports that anyway (or at least I hope so)
 
|-
 
|-
|itemizedlist||A list in which each entry is marked with a bullet or other dingbat|| definitely useful
+
|}
 +
 
 +
Unneded Tags:
 +
{||
 
|-
 
|-
|keycap||The text printed on a key on a keyboard||yes for consistent formatting?
+
!DocBook Tag!!Description!!Keep? (blank == no)
 
|-
 
|-
|keycombo||A combination of input actions||yes for consistent formatting?
+
|abstract||A summary||
 
|-
 
|-
|keyword||One of a set of keywords describing the content of a document||
+
|appendix||An appendix in a Book or Article||
 
|-
 
|-
|keywordset||A set of keywords describing the content of a document||
+
|authorgroup||Wrapper for author information when a document has multiple authors or collabarators||
 
|-
 
|-
|listitem||A wrapper for the elements of a list item||
+
|author||The name of an individual author||
 
|-
 
|-
|literal||Inline text that is some literal value|| yes, useful
+
|book||A book||
 
|-
 
|-
|mediaobject||A displayed media object (video, audio, image, etc.)||
+
|bookinfo||Meta-information for a Book||
 
|-
 
|-
|member||An element of a simple list||
+
|bridgehead||A free-floating heading||
 
|-
 
|-
|note||A message set off from the text|| yes, definitely
+
|citation||An inline bibliographic reference to another published work||
 
|-
 
|-
|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
+
|corpauthor||A corporate author, as opposed to an individual||
 
|-
 
|-
|orderedlist||A list in which each entry is marked with a sequentially incremented label|| yes, useful
+
|date||The date of publication or revision of a document||
 
|-
 
|-
|package|| A name of a software package (e.g. a RPM) || useful for automated tests
+
|edition||The name or number of an edition of a document||
 
|-
 
|-
|para||A paragraph||
+
|email||An email address||
 
|-
 
|-
|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
+
|figure||A formal figure, generally an illustration, with a title||
 
|-
 
|-
|part||A division in a book|| yes, but ADoc has its own structural elements anyway (same for chapter, formalpara, section and part)
+
|firstname||The first name of a person||
 
|-
 
|-
|partintro||An introduction to the contents of a part||
+
|firstterm||The first occurrence of a term||
 
|-
 
|-
|phrase||A span of text||
+
|imagedata||Pointer to external image data||
 
|-
 
|-
|preface||Introductory matter preceding the first chapter of a book||
+
|imageobject||A wrapper for image data and its associated meta-information||
 
|-
 
|-
|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
+
|index||An index||
 
|-
 
|-
|productname||The formal name of a product|| useful for automated testing
+
|inlinemediaobject||An inline media object (video, audio, image, and so on)||
 
|-
 
|-
|productnumber||A number assigned to a product|| useful for automated testing
+
|keyword||One of a set of keywords describing the content of a document||
 
|-
 
|-
|programlisting||A literal listing of all or part of a program|| definitely useful for e.g. code examples
+
|keywordset||A set of keywords describing the content of a document||
 
|-
 
|-
|prompt||A character or string indicating the start of an input field in a computer display||
+
|listitem||A wrapper for the elements of a list item||
 
|-
 
|-
|pubsnumber||A number assigned to a publication other than an ISBN or ISSN or inventory part number||
+
|mediaobject||A displayed media object (video, audio, image, etc.)||
 
|-
 
|-
|quote||An inline quotation||
+
|member||An element of a simple list||
 
|-
 
|-
|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.
+
|para||A paragraph||
 
|-
 
|-
|replaceable||Content that may or must be replaced by the user|| definitely useful
+
|partintro||An introduction to the contents of a part||
 
|-
 
|-
|revdescription||A description of changes in a revision||
+
|phrase||A span of text||
 
|-
 
|-
|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.
+
|preface||Introductory matter preceding the first chapter of a book||
 
|-
 
|-
|revision||An entry encapsulating a single revision in the history of the revisions to a document|| see above
+
|prompt||A character or string indicating the start of an input field in a computer display||
 
|-
 
|-
|revnumber||A document revision number||
+
|pubsnumber||A number assigned to a publication other than an ISBN or ISSN or inventory part number||
 
|-
 
|-
|row||A row in a table||sure, but ADoc handles tables its own way anyway
+
|quote||An inline quotation||
 
|-
 
|-
|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
+
|revdescription||A description of changes in a revision||
 
|-
 
|-
|section||A recursive section||yes, but ADoc has its own structural elements anyway (same for chapter, formalpara, section and part)
+
|revnumber||A document revision number||
 
|-
 
|-
 
|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 175: Line 198:
 
|-
 
|-
 
|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|| definitely useful for stuff like hostnames/IPs, device names, user and group names, ...
 
|-
 
|table||A formal table in a document||sure, but ADoc handles tables its own way anyway
 
|-
 
|tbody||A wrapper for the rows of a table or informal table||sure, but ADoc handles tables its own way anyway
 
 
|-
 
|-
 
|term||The word or phrase being defined or described in a variable list||
 
|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||
 
|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||sure, but ADoc handles tables its own way anyway
 
|-
 
|thead||A table header consisting of one or more rows||sure, but ADoc handles tables its own way anyway
 
|-
 
|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||
 
|userinput||Data entered by the user||
Line 199: Line 208:
 
|-
 
|-
 
|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|| 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|| ADoc supports that anyway (or at least I hope so)
 
 
|-
 
|-
 
|}
 
|}

Revision as of 14:40, 18 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.

Note: I have split the table into three parts to make it easier to read. If you modify an entry, make sure you move it to the correct table! Tags Suggested to be kept:

DocBook Tag Description Reason for Keeping
acronym An often pronounceable word made from the initial (or selected) letters of a name or phrase only if needed by i18n
application The name of a software program yes for automated tests
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)
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
example A formal example, with a title yes for consistent formatting?
filename The name of a file yes for consistent formatting?
guibutton, guilabel, guimenuitem, guimenu, guisubmenu Various GUI Elements I think we could do with just one tag for any GUI element, no need to distinguish buttons from menus imo
keycap, keycombo various key related elements yes for consistent formatting?
literal Inline text that is some literal value yes, useful
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
package A name of a software package (e.g. a RPM) useful for automated tests
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
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
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
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
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
systemitem A system-related item or term definitely useful for stuff like hostnames/IPs, device names, user and group names, ...

Tags desired, but already handled by AsciiDoc:

DocBook Tag Description Reason for Keeping
chapter A chapter, as of a book yes, but ADoc has its own structural elements anyway (same for chapter, formalpara, section and part)
colspec Specifications for a column in a table sure, but ADoc handles tables its own way anyway
emphasis Emphasized text that's definitely useful
entry A cell in a table sure, but ADoc handles tables its own way anyway
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)
important An admonition set off from the text yes, definitely
itemizedlist A list in which each entry is marked with a bullet or other dingbat definitely useful
note A message set off from the text yes, definitely
orderedlist A list in which each entry is marked with a sequentially incremented label yes, useful
part A division in a book yes, but ADoc has its own structural elements anyway (same for chapter, formalpara, section and part)
row A row in a table sure, but ADoc handles tables its own way anyway
section A recursive section yes, but ADoc has its own structural elements anyway (same for chapter, formalpara, section and part)
table A formal table in a document sure, but ADoc handles tables its own way anyway
tbody A wrapper for the rows of a table or informal table sure, but ADoc handles tables its own way anyway
tgroup A wrapper for the main content of a table, or part of a table sure, but ADoc handles tables its own way anyway
thead A table header consisting of one or more rows sure, but ADoc handles tables its own way anyway
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
warning An admonition set off from the text yes, definitely
xref A cross reference to another part of the document ADoc supports that anyway (or at least I hope so)

Unneded Tags:

DocBook Tag Description Keep? (blank == no)
abstract A summary
appendix An appendix in a Book or Article
authorgroup Wrapper for author information when a document has multiple authors or collabarators
author The name of an individual author
book A book
bookinfo Meta-information for a Book
bridgehead A free-floating heading
citation An inline bibliographic reference to another published work
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
email An email address
figure A formal figure, generally an illustration, with a title
firstname The first name of a person
firstterm The first occurrence of a term
imagedata Pointer to external image data
imageobject A wrapper for image data and its associated meta-information
index An index
inlinemediaobject An inline media object (video, audio, image, and so on)
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
mediaobject A displayed media object (video, audio, image, etc.)
member An element of a simple list
para A paragraph
partintro An introduction to the contents of a part
phrase A span of text
preface Introductory matter preceding the first chapter of a book
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
revdescription A description of changes in a revision
revnumber A document revision number
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
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
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
wordasword A word meant specifically as a word and not representing anything else