Re: [Groff] Draft paper: "Writing Effective Manual Pages"

[Alejandro López-Valencia]

At 09:32 p.m. 26/04/2004, Larry Kollar wrote:
> I've started a short document on writing what I call "effective" manpages 
> -- readable and useable with a variety of output formats. I hope it will 
> eventually become source material for other groff documentation (like my 
> "ms" reference) or UTP Revisited.
>
> HTML version: http://home.alltel.net/kollar/effman.html
> Source (ms+www): http://home.alltel.net/kollar/effman.tar.gz
>
> Comments and further tips are welcome. :-)


OK. You picked my curiosity and read it over the weekend. Overall I find it 
informative and to the point, but I disagree in your prolegomena and rather 
agree with Jorgen Grahn and Pete Phillips critique.

I then started to write my own, but realized that Jorgen had said already 
everything I wanted to say. I would only add the vitriolic twist to the 
matter :-) There is one little issue that, I think, hasn't been mentioned.

I believe that your ulterior intention is evangelizing, else you'd have 
written the document in DocBook :-). So...

In Section 1.0. Rather than saying that you can translate to DocBook, 
wouldn't be better to observe the lack of decent, if any, DockBook/TEI 
troff output backends? Show that TeX is not always a good-thing to use, 
because the level of knowledge and skill needed to produced custom output 
with TeX is a lot higher than with troff. Just look at the sorry quality of 
the DocBook documents produced with the TeX stylesheets of the Linux 
Documentation Project. Ah! And mention mm somewhere! My religious beliefs 
tell me that mm is better for long documents.

So there, I couldn't help being vitriolic after all. ;-)

BTW, I'll translate your document to Spanish as soon as you let us know you 
have a  final version.

Cheers

Alejo
--
Alejandro López-Valencia
http://dradul.tripod.com/
The limits of my language are the limits of my world.
                                    (L. Wittgenstein)