On Fri, 8 Jun 2007, Scott Smedley wrote:
Hi Victor,
* use more precise docbook tags in many places
Your changes are good. However, a cursory inspection of the HTML output
shows something isn't quite right. There's a strange character in the
section headings (after the section number).
eg. It looks like "1.,Name" instead of "1. Name".
I can't reproduce this. It seems to be a , which should be alright.
Also, the use of 2 <simplelist>s in fvwm/initialization.xml doesn't
have the desired effect (horizontal whitespace) in HTML output.
There were two <simplelist>s before. I just removed an empty paragraph
between them since that added lots of vertical whitespace in the
manoutput. I've reinserted it as htmlonly. (I take it that you mean
vertical whitespace)
* tables:
- The old manpage use manually written tables where needed,
the new use docbook generated tbl code for tables.
There is a docbook limitation that the entire table must either be
in borders or without them.
My opinion: tables look better with only iner borders, but it's
not worth hacking docbook to get around the limitation.
The most annoying thing (to me) about the table output is that it
doesn't make efficient use of horizontal space. I think it's a
limitation (bug?) of the tbl system.
I'm not sure if it's in the tbl system or in the docbook table to tbl
conversion. I looked at it some for the borders and figured that they
first convert it to html output, and then go from there to tbl output, so
they lose some of the formatting settings not used with htmloutput.
An additional note about the changes: some commands that earlier used
something that resembles an indented <variablelist> (just like the
variable list I changed) use tables instead now. These are the
context-rectanngle description of the Menu command, the formatting
directives od the ItemFormat menu style, the cursor style contexts and
environment variables in the ENVIRONMENT section. <variablelist>s use the
space better when the columns are of different length. Because of that I
think that some, maybe all, of these table should be changed to
variablelists. It would be good to be able to indent them like before, but
they look clear even without the extra indentation.
* examples:
- keywords in programlistings are marked up (since they are links)
but used to be displayed in plain text in the manpage.
My opinion: It's a lot of formatting in an example. Maybe fvwmrefs
in programlistings shouldn't add extra markup in manpage output.
The change is deliberate, but can be altered. Personally I like it
because it conveys extra information. What do other users think?
I'm not really decided here myself. It does add some information, but with
examples consisting of mostly keywords having them formatted makes it very
formatting dense. For the htmloutput it's all good, with the links to
follow.
- Subsubsections and subsubsubsection are typeset as subsections.
My opinion: should be fixed
Are you referring to indentation?
Mainly. Before subsubsection and subsubsubsections were typeset as
subsections are now, but indented further. In the htmloutput it's clear
which level each section has since they are numbered. In the new style
everything looks as subsections (since they aren't uppercase).
* missing sections:
- The sections AUTO-RAISE, BOOLEAN ARGUMENTS and
CONDITIONAL COMMANDS AND RETURN CODES are missing in the docbook
man page.
My opinion: The sections should be restored, unless a motivation
for not including them can be given.
AUTO-RAISE
It doesn't seem consistent to have extra info about a single module.
There's already a description of modules in the Module command section.
Agreed that it doesn't really fit. If it remains there should be similar
sections for some other module features, and it's hard to draw a line on
what should be mentioned and what shouldn't.
CONDITIONAL COMMANDS AND RETURN CODES
Useless. (IMO of course)
I agree as well, there is probably a reason why it was added in the firts
place, so I'd not remove it without asking.
/Viktor
