Re: [Groff] Re: Simplifying groff documentation

[Zvezdan Petkovic]

On Thu, Dec 28, 2006 at 11:11:34PM -0500, Eric S. Raymond wrote:
> > There is a deeper philosophical question here.
> > Who needs to tag a document for all the sorts of semantic or any other
> > meaning?  Is it the author or somebody else?
> 
> Who tags the man pages you write?  Who should tag them?

I think I answered that in the previous post.
There is a part where I said that the technical manuals absolutely
require this.  Since a great amount of effort is invested to produce
concise and precise manual, tagging is not a large part of the effort.

The only reason I began writing in DocBook was to make a precise How-To
document on a certain topic which could be easily translated to
different formats:

        - text for a terminal lookup (lynx -dump)
        - HTML for a browser lookup (GUI browser presumably)
        - print (non-technical people love this)

I thought that DocBook gives me all of the above and a semantic context
as a plus.  I do believe that it is an excellent format for technical
manuals and a very good documentation tool for system administrators,
for example.

> This isn't a silly or confrontational question -- because doclifter
> can turm your man pages into high-quality DocBook markup, it's
> actually the *same* question.

I know.  Please don't take my questions as confrontational.

What I was more concerned with is general writing.
Does an author of the book need to bother with semantic tagging on a
scale that DocBook _requires_?  Is it a task for a publisher if they
want it?  That's why I cited that anecdote about the old professor.
She simply thought it preposterous that she needs to learn how to type
and how to use a word processor -- she had a secretary for that. :-)

One could argue that she had a backwards view of the world and no
respect for other people's work.  But then, why don't we all go and work
on farms or beside a lathe in a factory to show a respect for people who
do the things we could have done on our own.  Or could we?

One could also argue that a person who has been educated for so long a
time to do a certain kind of work can spend her time more productively
than typing (or semantic tagging).  That's what might be wrong with
DocBook or any XML format.  People who have something to write about are
usually not happy spending time on a work unrelated to what they want to
write about (such as tagging).

Of course, if the publishers don't have to pay somebody else to typeset
or semantically tag the book (at least not completely), all the better
for them.  I doubt that authors writing in DocBook charge separately for
the semantic tagging.  On the other hand they certainly leave a good tip
if a waiter in a restaurant they dined in showed any extra effort in
serving them.

Does the semantic tagging make the book look better?
Does it make it express the ideas better?
Why the author should do it?

I'm a computer professional.
I tend to do all the things by myself.
I'm questioning whether I, or anyone else who does it themselves, should
reconsider.  Is the time invested worth it?

Best regards,

        Zvezdan