GNOME Bugzilla – Bug 633673
In DocBook sources, ItemizedLists should be VariableLists
Last modified: 2018-06-29 22:46:29 UTC
Throughout the XML source files, the <itemizedlist> tag is used repeatedly to create definition lists--that is, lists of terms and their definitions. To do this, doc writers have been forced to improvise formatting by making the term bold, then putting a dash to separate it from the definition, then finally putting in the definition. DocBook actually has a ready-made tag to handle definition lists--it's called <variablelist>.[1] VariableLists are automatically styled correctly so doc writers don't have to worry about the formatting. And, using tags to mark up terms and their definitions is more DocBook-ish :-) So I propose we convert all ItemizedLists to VariableLists. This should probably be done over several patches as there are quite a lot of ItemizedLists and getting them all in one go would result in a very hard-to-review patch. [1] http://www.docbook.org/tdg5/en/html/variablelist.html
I've looked into this bug and I must say that changing itemized to variable just don't look right in any case. IMHO it looks better only if the description following the term is at least 3-4 rows long. I also noticed that variablelist don't add a list sign (dot, square ecc...) ahead of the terms and in some cases this results in a lesser readable list.
Hi Cristian, (In reply to comment #1) > I've looked into this bug and I must say that changing itemized to variable > just don't look right in any case. IMHO it looks better only if the > description > following the term is at least 3-4 rows long. You're right that the current styling of the VariableLists has a lot of redundant spacing. Description lists look and work much better in something like LaTeX. That said, I feel this is a formatting issue and can be solved by customising the XSLT stylesheet. I know a little XSLT, but learning the multi-layered DocBook system is taking some time :-) I'm currently reading up on [1], in case you're interested. > I also noticed that variablelist don't add a list sign (dot, square ecc...) > ahead of the terms and in some cases this results in a lesser readable list. Another good point; generally, definition lists don't use a list symbol wingding as the `definition' part is indented slightly towards the right. So the term itself seems to `hang' to the left, which makes it stand out. E.g.: Term Definition of term. Second sentence of definition. Note that the definition is indented towards away from the left margin. Another Term Another definition. Still, the DocBook HTML output uses a blank line to separate the term and the definition, which is aesthetically unpleasing. This is a formatting thing we can correct. [1] http://www.sagehill.net/docbookxsl/Variablelists.html
Does anyone know whether the XSLT stylesheet for VariableLists has been updated to reflect the concerns raised here? If there is no intention to update the XSLT, then this bug should be closed as WONTFIX, since the issue has languished for 7 years without apparent crisis in the docs. If there is intention to update the XSLT (or the work has already been done), then perhaps the process could be restarted, so that the docs themselves can begin to have the itemizedlist tags replaced where needed. There are a lot of instances to check.
There are several lists defined in docbook: calloutlist, itemizedlist, orderedlist, simplelist, variablelist and segmentedlist, which can be displayd as list or table. Each has several attributes to adjust them. There might me some change of XSLTs in my project "update to Gnome-Doc-Utils" but I have to see. One could run 'grep -irn "list" .' in guide/C and help/C to check the appropriate use.
What will using gnome-doc-utils do for us?
(In reply to John Ralls from comment #5) > What will using gnome-doc-utils do for us? In our main files we have: <!-- (Do not remove this comment block.) Template Maintained by the GNOME Documentation Project: http://developer.gnome.org/projects/gdp Template version: 2.0 beta Template last modified Feb 12, 2002 --> GDU is it's successor. Some benefits of GDU: * OMFs are automatc generated, filling metadata like authors from the main files in a template. * Most templates in xsl would get updates. * in it it is already used for the po stuff. The problem: disable the po stuff for other languages.
GnuCash bug tracking has moved to a new Bugzilla host. The new URL for this bug is https://bugs.gnucash.org/show_bug.cgi?id=633673. Please continue processing the bug there and please update any external references or bookmarks.