English
Ask Your Question
2

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

asked 2011-10-04 06:38:32 +0000

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
3

answered 2011-10-12 14:01:08 +0000

Shaun gravatar image

updated 2011-10-12 16:28:42 +0000

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
edit flag offensive delete link more

Comments

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 ( 2011-10-12 15:31:53 +0000 )edit
2

answered 2011-10-12 11:26:37 +0000

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
2

answered 2011-10-12 13:27:07 +0000

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 :-)

edit flag offensive delete link more
2

answered 2011-10-12 21:09:44 +0000

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

Your Answer

Please start posting anonymously - your entry will be published after you log in or create a new account.

Add Answer

[hide preview]

Use your votes!

  • Use the 30 daily voting points that you get!
  • Up-vote well framed questions that provide enough information to enable people provide answers.
  • Thank your helpers by up-voting their comments and answers. If a question you asked has been answered, accept the best answer by clicking on the checkbox on the left side of the answer.
  • Down-voting might cost you karma, but you should consider doing so for incorrect or clearly detrimental questions and answers.

Question Tools

Follow
1 follower

Stats

Asked: 2011-10-04 06:38:32 +0000

Seen: 384 times

Last updated: Oct 12 '11