[MPlayer-DOCS] Proposal: split manpages

[Carl Fûrstenberg]

On Fri, 22 Oct 2004 22:58:26 +0200, Jonas Jermann <jjermann at gmx.net> wrote:
> 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
> 
> _______________________________________________
> MPlayer-DOCS mailing list
> MPlayer-DOCS at mplayerhq.hu
> http://mplayerhq.hu/mailman/listinfo/mplayer-docs
> 

1) yea, someone has do do it, as with everything here :)

2) personaly I do not like roff, it's to clutrish, stange macros here
and there I don't know anything what they are ment to be, for example
"'in +\n[.k]u" I don't know nada what it does.
personaly I loke to write in a language that is somewhat easy to use
in different ways. there I think xml is the best choise.