Ask Your Question

Which are the most used DocBook tags actually used by you in Fedora Guides?

asked 2011-10-04 01:38:32 -0500

tezcatl gravatar image

I bet many of you have written some chunks of Fedora Guides in DocBook. Maybe even you have edited significative chapters (or whole books ;-)).

Would you like share with the crowd, your most loved tags?

Let's say, for example, nobody can feel how is like learning functional programming without knowing about really fun things like: map, folds, lambdas, list comprehensions, and so on.

Do you think we can arrange a list like that for DocBook?

In my humble opinion I bet it can't be that interesting just turning the most used HTML tags like <p>, lists and links, into more verbose equivalents. Or attribution tags to Meta properties.

Maybe you could enlighten wannabe doc-writers, showing us the most interesting tags, the first subset every new doc writer must to learn, to avoid cheating using pandoc ;-) to compose from markdown and turning it into docbook to let people engage in translation.

edit retag flag offensive close merge delete

4 Answers

Sort by ยป oldest newest most voted

answered 2011-10-12 09:01:08 -0500

Shaun gravatar image

updated 2011-10-12 11:28:42 -0500

Here's an actual quantitative breakdown of GNOME's DocBook manuals in 2005:

Edit: I've long-since lost the script I originally wrote for this, but I recreated it fairly easily using the awesome xmlstarlet tool. (It's just a yum install away.)

For doc in YOUR-DOCS-HERE; do
  xmllint --xinclude --noent "$doc" | xmlstarlet sel -t -m '//*' -v 'local-name(.)' -n -;
done | sort | uniq -c
edit flag offensive delete link more


Interesting, but I'm not sure how much GNOME's manuals from six years ago match up with Fedora docs from today. For example, most of the Gnome docs just use "section" and not "sect1" and "sect2" tags. Might be interesting to re-run a similar script against a few Fedora guides.

jsmith gravatar imagejsmith ( 2011-10-12 10:31:53 -0500 )edit

answered 2011-10-12 08:27:07 -0500

The most common tag is <para>, as almost all the "real" text of document is contained in paragraphs.

Paragraphs are organized into sections, so the <section> tag is obviously quite common as well. A section can have a title, so the <title> tag is quite common as well.

Footnotes are added via the <footnote> tag. (Of course, you'll typically have a <para> tag inside of the footnote.)

External links are done via the <ulink> tag. Internal links are typically done via the <xref> tag.

Admonitions (notes, warnings, and important items) are done with <note>, <warning>, and <important> tags. They'll typically include a <title> and a one or more <para> tags.

Since most documentation done in DocBook is of a technical nature, it's very common to use tags such as <application> or <function> or <command> to highlight applicatoins, functions, and commands. Screen output from the computer is typically placed inside of a <screen> tag, and program listings are placed inside of a <programlisting> tag.

The tags I've mentioned probably cover at least 80% of the tags used in DocBook. I highly recommend that you check out for a complete listing of the tags in DocBook 4, including their usage and meaning and examples. It's the definitive guide for a reason :-)

edit flag offensive delete link more

answered 2011-10-12 06:26:37 -0500

jjmcd gravatar image

Obviously, the <para> tag is by far the most used. My initial reaction would be that <section> was next, but in fact, it has to be <title>, since every section and every admonition needs a title.

I think my favorites are the admonitions; <note>, <important> and <warning>, not because they get used so much, but because the Publican result is so nice.

edit flag offensive delete link more

answered 2011-10-12 16:09:44 -0500

sgordon gravatar image

It really depends on the guide, but I ran a quick check on one of my guides and came up with the following counts. Note that I probably haven't correctly picked up elements with attributes...

 10 <note>
 10 <row>
 11 <important>
 12 <procedure>
 13 <replaceable>
 13 <substeps>
 18 <citetitle>
198 <step>
  1 <abstract>
  1 <affiliation>
  1 <authorgroup>
  1 <bridgehead>
  1 <chapter>
  1 <corpauthor>
  1 <edition>
  1 <indexterm>
  1 <inlinemediaobject>
  1 <orgdiv>
  1 <orgname>
  1 <primary>
  1 <productname>
  1 <productnumber>
  1 <pubsnumber>
  1 <revhistory>
  1 <secondary>
  1 <tbody>
  1 <variablelist>
200 <listitem>
 20 <entry>
 23 <package>
244 <guilabel>
 24 <example>
254 <acronym>
 25 <filename>
290 <title>
 29 <parameter>
  2 <subtitle>
  2 <uri>
 32 <mediaobject>
 33 <imageobject>
  3 <date>
  3 <guimenu>
  3 <guimenuitem>
  3 <guisubmenu>
  3 <member>
  3 <menuchoice>
  3 <partintro>
  3 <revdescription>
  3 <revision>
  3 <revnumber
  3 <revnumber>
  3 <section>
  3 <simplelist>
  3 <term>
  3 <varlistentry>
 40 <formalpara>
 42 <systemitem>
 44 <itemizedlist>
 45 <application>
 45 <guibutton>
  4 <author>
  4 <emphasis>
  4 <figure>
  4 <firstname>
  4 <firstterm>
  4 <remark>
  4 <simpara>
  4 <surname>
 54 <screen>
  5 <email>
  5 <phrase>
  5 <textobject>
  5 <warning>
 62 <literal>
666 <para>
 67 <keycap>
 70 <command>
  7 <orderedlist>
  7 <stepalternatives>
edit flag offensive delete link more

Question Tools

1 follower


Asked: 2011-10-04 01:38:32 -0500

Seen: 426 times

Last updated: Oct 12 '11