On Thu, 7 Jun 2007, FVWM CVS wrote:
* use more precise docbook tags in many places
* use variablelist for the fvwm variable list instead of table
* make environment variables and keysyms typeset as before
I've started to compare the generated man page with the old hand written,
and the above changes are some small changes that makes the generated
manpage look more likte the original in some aspects. There are still
several differences, some which are good, some which doesn't matter, and
some which are bad. I'm not sure how many of the are intended and how
many are a result of bad automatic conversion.
* alignment:
- The old manpage is justified, the generated man page is
left-aligned.
My opinion: don't care
* 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.
* section spacing:
- In the old manpage most sections had an extra line at the end.
(Some sections had more, some had less.) The generated manpage
have all one line between sections.
My opinion: don't care
* 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.
* sentence spacing:
- sentences in the old manpage are separated with two spaces.
Docbook uses single spaces everywhere. It should be possible to
somehow add extra spaces between sentences.
My opinion: don't care, seems to be a lot of work
* url markup:
- Urls are marked up with italic instead of bold.
My opinion: italic looks better for urls than bold did
- Urls are not split over lines with docbook.
My opinion: don't care, leaves a lot of white space on the line
before. With justified alignment they have to break.
* lists:
- list take up more space in docbook.
My opinion: case to case basis. Most lists have sort items, so
they will never split over multiple lines, so it will just be lots
of extra whitespace as a result.
- itemized lists use bullets instead of hyphens
My opinion: don't care
* indentation:
- Some items are indented one level less than the original manpage
My opinion: as long as it looks OK I don't care
* sections:
- Subsections are typeset withoutupper case in docbook. The old
man page used uppercase for both sections and subsections.
My opinion: don't care
- Subsubsections and subsubsubsection are typeset as subsections.
My opinion: should be fixed
* commands:
- used to have their own synapsis on the title line, now on its
own line.
My opinion: the old way looks better
* 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.
/Viktor
