Docs Tag Discussion

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 four 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 (2 tables)

Converted in initial attempts:

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
filename	The name of a file	yes for consistent formatting?
guibutton, guilabel, guimenuitem, guimenu, guisubmenu, keycap, keycombo	Various GUI and key Elements	I think we could do with just one tag for any GUI element, no need to distinguish buttons from menus imo
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
replaceable	Content that may or must be replaced by the user	definitely useful
systemitem	A system-related item or term	definitely useful for stuff like hostnames/IPs, device names, user and group names, ...

Not to be retained in initial conversions, but worth revisiting as we work with output.

DocBook Tag	Description	Reason for Keeping
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?
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.
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

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