Re: [Groff] Re: Simplifying groff documentation

[Meg McRoberts]

Eric, I really like your long-term vision, but have some questions
to extend it a bit.

If all this were implemented, would you envision that people writing
new man pages would write them using -man or would they use docbook?

My concern right now is with man pages for third-party software.
I work for a company that produces software that runs on Linux,
Solaris, and Windows.  For the versions that run on Linux, I have
advocated creating man pages for commands and configuration files
that are used.  This works well as long as I am writing them but
the *roff world is pretty intimidating to these kids who have grown
up with Word and FrameMaker and the effort required to become proficient
is not warranted for the small amount of docs that are done.

I'm not sure of the solution but it seems that, if they could write in
docbook, this opens the option of using an XML WYSIWYG editor if necessary.

How does this fit into your vision of the future?

meg

--- "Eric S. Raymond" <address@hidden> wrote:

> Zvezdan Petkovic <address@hidden>:
> > > For someone as bothered by tag verbosity as you are I would recommend
> > > using asciidoc, which can generate DocBook.
> > 
> > I wonder why asciidoc?
> 
> Because it's the simplest way to compose DocBook-structured stuff I've
> seen yet.
> 
> > Is it really any different from docutils that we are supposed to use for
> > Python program documentation?
> > How about POD that we are supposed to use for Perl program
> > documentation?
> > I think I've learned enough "standard" documentation formats.
> 
> You left out Texinfo :-).
> 
> My vision is that all of these feed into DocBook, which then 
> (a) becomes the transfer format everybody uses, and (b) has a
> common back end for rendering HTML or print that everyone can use.
> 
> Thus, you would be able use any "standard" format you like for composition.
> Past the point where it got turned unto DocBook, nothing would care.
> 
> But this wouldn't be worth doing for its own sake.  The goal is to
> change the way Unix documentation is presented so that it all comes through 
> the user's browser and has hyperlinks to everywhere.  
> 
> We can't get there without converging all the formats at some point.  
> Where the path I'm advocating differes from the ad-hoc, 
> bash-everything-to-HTML-with-its-own-converter approach is that it
> captures (or deduces) more semantic information at an earlier stage.
> I think this is worth doing because when you do that you get better
> HTML out the other end.
> 
> > 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?
> 
> 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.
> -- 
>               <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>
> 
> 
> _______________________________________________
> Groff mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/groff
>