RFC: Upgrading to DocBook 5.0

[Gabor Kovesdan]

On 2013.07.14. 18:02, Warren Block wrote:
> On Sun, 14 Jul 2013, Gabor Kovesdan wrote:
>
>> Em 14-07-2013 14:52, Warren Block escreveu:
>>> On Sun, 14 Jul 2013, Gábor Kövesdán wrote:
>>>
>>>> Some more things:
>>>>
>>>> - Admonitions (top, note, warning boxes) look quite strange in 
>>>> lists and such places. I think we should add a policy to avoid them 
>>>> and start changing the markup.
>>>
>>> Admonitions are overused in some places.  They are visually jarring, 
>>> often moreso than the tip or warning deserves.  A link to an example 
>>> of this particular problem would be helpful to see what you mean, 
>>> though.
>> For example here: 
>> http://www.freebsd.org/doc/en/books/handbook/history.html
>>
>> It breaks the list. It is even worse in PDF rendering since there are 
>> page boundaries and it breaks the page up to two parts.
>
> I see what you mean.  But if we say "don't use admonitions in lists 
> because they are visually ugly, that becomes markup for appearance and 
> not for semantics.
It is not appearance, it is structure, which is part of semantics. From 
a semantic point of view, what's an admonition? Imo, it is a piece of 
additional information that (1) is related to the wider context, (2) is 
more or less self-contained and (3) does not fit into the main text flow 
so its position is more or less flexible. It is usually rendereded with 
a border or a background color that clearly separates it from the main 
flow of the text. Because of these characteristics, it semantically 
doesn't fit into the notion of lists. Nor tables should be embedded into 
lists.
>
> Some tweaking of the CSS may help, like reducing the size of the 
> admonition title so it is not so much larger than the surrounding 
> text. docbook.css is something I've been meaning to look at, hopefully 
> soon.
It may help but that break of information flow still shouldn't be there.
>
>>>> - We extensively use markup in titles, which later renders with a 
>>>> different font. E.g. we mark the X of 9.X as replaceable or we mark 
>>>> up root as a username. I think that such rendering should be 
>>>> avoided in titles and the easiest and cleanest way to do so would 
>>>> be not using such markup in titles.
>>>
>>> Please expand--what is the problem with differing fonts in titles?  
>>> I can see this both ways, but the text of a title being consistent 
>>> with the rendering in the body seems like an advantage.
>> Apart from the ugly visual outlook, it is not conventional in books 
>> and as such, it is just bothering and confusing for the reader. It 
>> breaks the information flow. Typographyc conventions serve for nice 
>> visual outlook and usability. The typesetting should facilitate 
>> reading and not difficulting it. If we want to publish a high-quality 
>> print edition of Handbook, we must follow the conventions, otherwise 
>> it won't be a serious publication.
>
> Again, doesn't this break the semantics versus appearance separation? 
> If the standard is to show titles in a single font and size, then that 
> should be done when rendering.  Semantically, a filename is a filename 
> whether it is in a title or body text.
You are calling appearance what is in fact structure. We could talk 
about appearance if we wrote <bold> or something like that.

The semantics of a title could be defined like a plain text title and 
that would be a valid semantics, too. True, it is also possible to solve 
it when rendering but if we decide that we don't want such in titles, 
why not just changing the semantics and sparing some stylesheet code? 
Both the docs and the stylesheets would be more simple.
>
> I find different fonts for filenames and commands to be useful, even 
> in titles.  The O'Reilly style guide doesn't mention anything about 
> title styles, and in a quick search I did not find anything else.
Ok, it doesn't specify it explicitly but can you show me a technical 
book that has such titles? A real, published book, please, not online docs.
>
>>>> - Currently, we use the CALS table model in the documentation, 
>>>> while DocBook also supports the HTML table model. It has a more 
>>>> simple syntax and more rendering features in the DocBook 
>>>> stylesheets. Another advantage is that by using it, we would have 
>>>> only one table semantics in docs + web. Any objection to changing 
>>>> to the HTML table model?
>>>
>>> An example would be useful here, also.  For compatibility with the 
>>> rest of the world, we should probably stick with the most common usage.
>> Most common is very relative. HTML uses exclusively the HTML table 
>> model, hence the name. CALS is older and quite common in the SGML/XML 
>> world. Both are supported in DocBook and we currently use CALS. 
>> Earlier there was no other option in DocBook. Using exclusively HTML 
>> tables would reduce the used table models to one.
>>
>> Examples: just google for CALS table and HTML table, both are 
>> documented extensively.
>
> For reference, here are links:
>
> http://www.docbook.org/tdg5/en/html/cals.table.html
> http://www.docbook.org/tdg5/en/html/html.table.html
>
> Changing the source documents could be scripted, but would also 
> require modifications to the FDP Primer.
>
> I can't tell if HTML tables have all the same capabilities as CALS 
> tables.
The same information is stored so theoretically it is possible to do the 
same with them. HTML table markup is more simple and the stock 
stylesheets implement more features.
>
>>>> - Some lists have their own title, while the preceding text usually 
>>>> introduces well what is enumerated in the list. I find the rendered 
>>>> title quite strange between this text and the list. Besides, I 
>>>> don't remember having seen technical books that use such titles. My 
>>>> suggestion is to simple remove them. Any objection or better idea?
>>>
>>> Please give an example here, also.
>> http://www.freebsd.org/doc/en/books/handbook/bsdinstall-pre.html
>>
>> Look at 2.3.3.  There's a semicolon at the end of the last paragraph 
>> and list title is just floating there in the middle. This type of 
>> titles breaks the flow of the text and doesn't facilitate reading.
>
> The previous toolchain rendered that title in bold:
> http://docs.freebsd.org/doc/9.0-RELEASE/usr/share/doc/freebsd/en_US.ISO8859-1/books/handbook/bsdinstall-pre.html 
>
>
> Agreed, that title does not look very good.  Adding a colon to list 
> titles when rendering would help.  Removing all list titles be too 
> severe.
Having a colon at the end of the paragraph and another one at the end of 
the list title? It seems even more confusing to me.
Why is to severe removing them? Do they add any extra information that 
helps you understanding the content? I think it makes the comprehension 
more difficult and is just counter-productive.

Can you find a published book with such list titles?

Gabor