[MPlayer-DOCS] Proposal: split manpages

[Jonas Jermann]

On Fri, Oct 22, 2004 at 10:35:27PM +0200, Carl Fûrstenberg wrote:
> On Fri, 22 Oct 2004 21:54:31 +0200, Jonas Jermann <jjermann at gmx.net> wrote:
> > On Fri, Oct 22, 2004 at 02:17:55PM -0400, D Richard Felker III wrote:
> > > On Fri, Oct 22, 2004 at 07:24:16PM +0200, Dominik 'Rathann' Mierzejewski wrote:
> > > > > first we have row 4762 to 7133 that is mencoder only, then it's a lot
> > > > > of sections marked mplayer only. also it's many places thats marked
> > > > > only suitable in mplayer/mencoder.
> > > > >
> > > > > I just proposed to split out everything that was mencoder only to a own
> > > > > manpage.
> > > >
> > > > We've been discussing it with Rich in another thread (last month?)
> > > > and on IRC. There was an idea to split some common parts like
> > > > codecs, filters and audio filters into separate manpages. Rich, are
> > > > you still in favour of that?
> > >
> > > iirc i was never in favor of it, but i might not be too opposed if
> > > it's done in a sane way. but i really juet like being able to run "man
> > > mplayer", hit the slash key, and instantly find any topic i want for
> > > mplayer or mencoder. breaking up into lots of little man pages makes
> > > finding the info you want a lot slower!
> > 
> > I agree. I don't have a problem with a big man page...
> > 
> > A sane way for me would be to somehow generate both man pages
> > mplayer.1 and mencoder.1 from a common file, but as (g)roff is soo much broken
> > you will _most_ probably not be able to do it without conversion problems.
> > One reason to say this is the mess I saw when I checked how to generate
> > html/txt/other output _from_ a man page. _Every_ program had it's flaws and we
> > ended up changing the man page itself to produce a nice html output (imo not
> > a good idea). It's just a bad, ugly format (imo). ;)
> > 
> > But perhaps it could be done with a normal perl script that uses some meta
> > information (non visible comments) that converts the huge man page into
> > mplayer/mencoder parts by just filtering out specific lines, donno...
> > 
> > Regards
> >         Jonas
> > 
> > 
> > 
> > _______________________________________________
> > MPlayer-DOCS mailing list
> > MPlayer-DOCS at mplayerhq.hu
> > http://mplayerhq.hu/mailman/listinfo/mplayer-docs
> > 
> 
> I before attached a little xsl-file that could convert xml to
> man-page, it would be easy to add a tag 'only="mencoder"' or
> 'only="mplayer"', and when parsing it put right thing in right
> manpage. also if made in xml there is much easier to produce html.

In my opinion there are two problems with this:

1) Someone has to do it. ;)
2) I don't trust converters, they often lead to problems in one or
   another way especially with roff as it is full of small
   macros/stuff that don't seem to make sense...

Personally I'd really prefer to keep the documentation in the form it
will be distributed. The xml documentation is a bit an exception but the
man page is really mainly used as the man page, so I don't see much sense
in using a common format.

It's also easy to do what you describe without forcing xml and the
main man page could still be used without conversion tools.


Regards
	Jonas