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

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 close merge delete

Sort by » oldest newest most voted

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

http://blogs.gnome.org/shaunm/2005/10/21/how-much-docbook/

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

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.

( 2011-10-12 10:31:53 -0500 )edit

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 http://docbook.org/tdg/en/html/docbook.html 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 :-)

more

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.

more

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 <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 <member>
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>

more