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.
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.
- 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.
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.
- 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.
- 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.
All of these suggestions seem to be style changes that are not necessarily
tied to the change to DocBook 5, or maybe changes that are not possible
until after the conversion. Unless they're required, it may be best to
wait until after the conversion.
Not in theory but theory doesn't always match practice. I'm working on the
DocBook 5 change to provide better rendering and support publishing print
versions. I'm evaluating and customizing two different rendering methods and
I have to see where we can get with each. Practically I can do it by
eliminating the confusing and bothering factors. This is sometimes done by
customizing the rendering and sometimes by feeding back the results to the
concrete documents.
Understood. Thank you for working on this!
_______________________________________________
[email protected] mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "[email protected]"
