[MPlayer-DOCS] Proposal: split manpages

[Jonas Jermann]

On Fri, Oct 22, 2004 at 11:07:56PM +0200, Carl Fûrstenberg wrote:
> 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 :)

Yeah, exactly ;)

> 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.

I do not like roff neither, but it is the language used in man page,
I really see no sense in preventing that it isn't and I don't believe
it's possible to convert every ugly thing of roff into a "nice" xml
equivalent. You'll end up having the same mess in xml. I just prefer the
"original" language rather than whole conversion framework as far as possible.
But I think I explained my position already, so this is probably my
last mail on this thread...


Regards
	Jonas