I would like to propose to split the manpage into two, one for mplayer and one for mencoder. Primary beacuse now the manpage is very long, and seccondary because if you using mencoder, you migt want to write man mencoder and only get what's for mencoder, not to have to scroll down 100 pages.
On Fri, Oct 22, 2004 at 12:06:30AM +0200, Carl Fûrstenberg wrote:
I would like to propose to split the manpage into two, one for mplayer and one for mencoder. Primary beacuse now the manpage is very long, and seccondary because if you using mencoder, you migt want to write man mencoder and only get what's for mencoder, not to have to scroll down 100 pages.
it was discussed many times before. please read the archives. rich
On Thu, 21 Oct 2004 18:55:26 -0400, D Richard Felker III <dalias@aerifal.cx> wrote:
On Fri, Oct 22, 2004 at 12:06:30AM +0200, Carl Fûrstenberg wrote:
I would like to propose to split the manpage into two, one for mplayer and one for mencoder. Primary beacuse now the manpage is very long, and seccondary because if you using mencoder, you migt want to write man mencoder and only get what's for mencoder, not to have to scroll down 100 pages.
it was discussed many times before. please read the archives.
rich
_______________________________________________ MPlayer-DOCS mailing list MPlayer-DOCS@mplayerhq.hu http://mplayerhq.hu/mailman/listinfo/mplayer-docs
Tried to find, but no luck, is ther any way to search old archives, or can you piont me to where it was discussed?
Carl Fûrstenberg wrote:
On Thu, 21 Oct 2004 18:55:26 -0400, D Richard Felker III <dalias@aerifal.cx> wrote:
On Fri, Oct 22, 2004 at 12:06:30AM +0200, Carl Fûrstenberg wrote:
I would like to propose to split the manpage into two, one for mplayer and one for mencoder. Primary beacuse now the manpage is very long, and seccondary because if you using mencoder, you migt want to write man mencoder and only get what's for mencoder, not to have to scroll down 100 pages.
it was discussed many times before. please read the archives.
rich
Tried to find, but no luck, is ther any way to search old archives, or can you piont me to where it was discussed?
_
http://www1.mplayerhq.hu/pipermail/mplayer-docs/2004-January/001013.html Here for example, just follow thread. Jiri
On Fri, Oct 22, 2004 at 12:53:52AM +0200, Carl F?rstenberg wrote:
Tried to find, but no luck, is ther any way to search old archives,
http://www.mplayerhq.hu/cgi-bin/s-arch.cgi?sbm=mplayer-dev-eng or http://news.gmane.org/gmane.comp.video.mplayer.devel And about splitting - if you come with a sensible way of doing it, than maybe. But "sensible" means (as was discussed before) everything needed to use M{Player,Encoder} is in m{player,encoder}.1 (so no mplayer-common.1 or so, and nothing like "see also mplayer.1" in mencoder.1. And it also means no text duplication in CVS, as this will for sure get out of sync. Any ideas? If you have a good one, I can help you with the build system. Torinthiel -- Waclaw "Torinthiel" Schiller GG#: 542916, 3073512 torinthiel(at)megapolis(dot)pl gpg: B06901F1 fpr: FAA3 559F CAE9 34DE CDC8 7346 2B6E 39F2 B069 01F1 "No classmates may be used during this examination"
Torinthiel wrote:
On Fri, Oct 22, 2004 at 12:53:52AM +0200, Carl F?rstenberg wrote:
Tried to find, but no luck, is ther any way to search old archives,
http://www.mplayerhq.hu/cgi-bin/s-arch.cgi?sbm=mplayer-dev-eng or http://news.gmane.org/gmane.comp.video.mplayer.devel
And about splitting - if you come with a sensible way of doing it, than maybe. But "sensible" means (as was discussed before) everything needed to use M{Player,Encoder} is in m{player,encoder}.1 (so no mplayer-common.1 or so, and nothing like "see also mplayer.1" in mencoder.1. And it also means no text duplication in CVS, as this will for sure get out of sync. Any ideas? If you have a good one, I can help you with the build system. Torinthiel
What about split mplayer.1 into separate files in common format (i.e. XML) by sections (header.xml; ...; codecsopt.xml, etc.). Then you can have one original in cvs and in main files (mplayer.xml; mencoder.xml) will be include commands only. Well it's idea only :-) Jiri
On Fri, Oct 22, 2004 at 11:31:19AM +0200, Jiri Heryan wrote:
Torinthiel wrote:
On Fri, Oct 22, 2004 at 12:53:52AM +0200, Carl F?rstenberg wrote:
Tried to find, but no luck, is ther any way to search old archives,
http://www.mplayerhq.hu/cgi-bin/s-arch.cgi?sbm=mplayer-dev-eng or http://news.gmane.org/gmane.comp.video.mplayer.devel
And about splitting - if you come with a sensible way of doing it, than maybe. But "sensible" means (as was discussed before) everything needed to use M{Player,Encoder} is in m{player,encoder}.1 (so no mplayer-common.1 or so, and nothing like "see also mplayer.1" in mencoder.1. And it also means no text duplication in CVS, as this will for sure get out of sync. Any ideas? If you have a good one, I can help you with the build system. Torinthiel
What about split mplayer.1 into separate files in common format (i.e. XML) by sections (header.xml; ...; codecsopt.xml, etc.). Then you can have one original in cvs and in main files (mplayer.xml; mencoder.xml) will be include commands only.
Well it's idea only :-)
imo the amount of infor that's _not_ duplicate between mplayer and mencoder is relatively very small. as such, i don't see a good justification for splitting the man page.. btw man files are not .xml... :) rich
On Fri, 22 Oct 2004 05:55:53 -0400, D Richard Felker III <dalias@aerifal.cx> wrote:
On Fri, Oct 22, 2004 at 11:31:19AM +0200, Jiri Heryan wrote:
Torinthiel wrote:
On Fri, Oct 22, 2004 at 12:53:52AM +0200, Carl F?rstenberg wrote:
Tried to find, but no luck, is ther any way to search old archives,
http://www.mplayerhq.hu/cgi-bin/s-arch.cgi?sbm=mplayer-dev-eng or http://news.gmane.org/gmane.comp.video.mplayer.devel
And about splitting - if you come with a sensible way of doing it, than maybe. But "sensible" means (as was discussed before) everything needed to use M{Player,Encoder} is in m{player,encoder}.1 (so no mplayer-common.1 or so, and nothing like "see also mplayer.1" in mencoder.1. And it also means no text duplication in CVS, as this will for sure get out of sync. Any ideas? If you have a good one, I can help you with the build system. Torinthiel
What about split mplayer.1 into separate files in common format (i.e. XML) by sections (header.xml; ...; codecsopt.xml, etc.). Then you can have one original in cvs and in main files (mplayer.xml; mencoder.xml) will be include commands only.
Well it's idea only :-)
imo the amount of infor that's _not_ duplicate between mplayer and mencoder is relatively very small. as such, i don't see a good justification for splitting the man page..
btw man files are not .xml... :)
rich
_______________________________________________ MPlayer-DOCS mailing list MPlayer-DOCS@mplayerhq.hu http://mplayerhq.hu/mailman/listinfo/mplayer-docs
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.
On Friday, 22 October 2004 at 14:23, Carl F?rstenberg wrote:
On Fri, 22 Oct 2004 05:55:53 -0400, D Richard Felker III <dalias@aerifal.cx> wrote:
On Fri, Oct 22, 2004 at 11:31:19AM +0200, Jiri Heryan wrote:
Torinthiel wrote:
On Fri, Oct 22, 2004 at 12:53:52AM +0200, Carl F?rstenberg wrote:
Tried to find, but no luck, is ther any way to search old archives,
http://www.mplayerhq.hu/cgi-bin/s-arch.cgi?sbm=mplayer-dev-eng or http://news.gmane.org/gmane.comp.video.mplayer.devel
And about splitting - if you come with a sensible way of doing it, than maybe. But "sensible" means (as was discussed before) everything needed to use M{Player,Encoder} is in m{player,encoder}.1 (so no mplayer-common.1 or so, and nothing like "see also mplayer.1" in mencoder.1. And it also means no text duplication in CVS, as this will for sure get out of sync. Any ideas? If you have a good one, I can help you with the build system. Torinthiel
What about split mplayer.1 into separate files in common format (i.e. XML) by sections (header.xml; ...; codecsopt.xml, etc.). Then you can have one original in cvs and in main files (mplayer.xml; mencoder.xml) will be include commands only.
Well it's idea only :-)
imo the amount of infor that's _not_ duplicate between mplayer and mencoder is relatively very small. as such, i don't see a good justification for splitting the man page..
btw man files are not .xml... :) [aieee! cut the sigs, please!]
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? R. -- MPlayer RPMs maintainer: http://greysector.rangers.eu.org/mplayer/ "I am Grey. I stand between the candle and the star. We are Grey. We stand between the darkness ... and the light." -- Delenn in Grey Council in Babylon 5:"Babylon Squared"
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! rich
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
On Fri, 22 Oct 2004 21:54:31 +0200, Jonas Jermann <jjermann@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@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.
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@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@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
On Fri, 22 Oct 2004 22:58:26 +0200, Jonas Jermann <jjermann@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@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@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@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.
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@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@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@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@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
On Fri, 22 Oct 2004 23:42:11 +0200, Jonas Jermann <jjermann@gmx.net> wrote:
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...
I put the mess into the xsl-sheet, you think my xml-sheet is a mess?
like for example, processing with "xsltproc -o mplayer.1 --stringparam part mplayer man.xsl man.xml" and "xsltproc -o mencoder.1 --stringparam part mencoder man.xsl man.xml"
On Fri, Oct 22, 2004 at 11:42:37PM +0200, Carl F?rstenberg wrote:
like for example, processing with "xsltproc -o mplayer.1 --stringparam part mplayer man.xsl man.xml" and "xsltproc -o mencoder.1 --stringparam part mencoder man.xsl man.xml"
kraken:~/tmp/test$ xsltproc -o mplayer.1 --stringparam part mplayer man.xsl man.xml man.xsl:10: error: Input is not proper UTF-8, indicate encoding ! <xsl:text>.\" Parser made by Carl Fürstenberg Adding encoding to <?xml?> in both files did help. But looking at generated file: ouch it outputs in utf-8, not saying so: .\" Parser made by Carl FĂźrstenberg it outputs lots of linebreaks where I see no sense for one: 'in +\n[.k]u \ [\ \ option\ \ ]\ \ [\ \ \ (these fit '\$' not '\ $' regexps) Whoa, this is even worse: .I \h'-1'title \h'-1'\ \ \ \ |\ \ \ \ [ And a line of 510 chars (it outputs every paragraph as a single line) isn't making me happier. By some unknown reason the first block of key descriptions (arrows, pgup/down etc.) is indented more then the second one (1-4, brightness/contrast). And I find the MM-DD-YY date format illogical and ugly, but that's just my personal preference and I see it written verbatim in .xml, so that's not an issue. Anyway, the xml is not really much more readable, I see it just as translating obscure groff commands to maybe a little less obscure, but much longer, xml tags. I'm not a big fan of groff, I've thrown a lot of curses at it when translating manpage to Polish, but I don't see why xml is so much better. It's just adding an extra layer of complexity and extra set of dependencies (xsltpros is not available everywhere) and most of what xsltproc does is a bit more complicated sed script. Torinthiel -- Waclaw "Torinthiel" Schiller GG#: 542916, 3073512 torinthiel(at)megapolis(dot)pl gpg: B06901F1 fpr: FAA3 559F CAE9 34DE CDC8 7346 2B6E 39F2 B069 01F1 "No classmates may be used during this examination"
And a line of 510 chars (it outputs every paragraph as a single line) isn't making me happier.
By some unknown reason the first block of key descriptions (arrows, pgup/down etc.) is indented more then the second one (1-4, brightness/contrast).
And I find the MM-DD-YY date format illogical and ugly, but that's just my personal preference and I see it written verbatim in .xml, so that's not an issue.
Anyway, the xml is not really much more readable, I see it just as translating obscure groff commands to maybe a little less obscure, but much longer, xml tags. I'm not a big fan of groff, I've thrown a lot of curses at it when translating manpage to Polish, but I don't see why xml is so much better. It's just adding an extra layer of complexity and extra set of dependencies (xsltpros is not available everywhere) and most of what xsltproc does is a bit more complicated sed script.
Torinthiel
ok, you have right it that, It's an ugly script, I just show'd how it could be done. Why it's so much newlines is because I do not know how to write *roff. But I was thinking it must be a better way to do it ? I can't hardly belive that every project is über in writing their own manpages. there must be a way. I also checked in pod, worked for a part, but did cut of efter a bit (don't know why). So for now I'll just translate the manpage as it is. I will problably write totaly wrong, but what the heck, I can't *roff... :)
On Fri, Oct 22, 2004 at 10:58:26PM +0200, Jonas Jermann wrote:
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.
i'm absolutely against xml for the man page unless the xml->man conversion can be done with no external dependencies whatsoever. it's bad enough to need some silly xml progs to generate the docs (but i don't read docs anymore anyway, or if i do i can just find them on the website). but not being able to read the manpage from cvs without having special doc tools installed would really suck!! (and it would lead to users not rtfm'ing!!! :/ ) rich
On Saturday 23 October 2004 06:17, D Richard Felker III wrote:
i'm absolutely against xml for the man page unless the xml->man conversion can be done with no external dependencies whatsoever. it's bad enough to need some silly xml progs to generate the docs (but i don't read docs anymore anyway, or if i do i can just find them on the website). but not being able to read the manpage from cvs without having special doc tools installed would really suck!! (and it would lead to users not rtfm'ing!!! :/ )
I agree. No special tools. Isn't it possible to have something like this: (i'm not a roff expert, so don't laugh) Have a common header and footer, have an mplayer specific file and mencoder specific file and build scripts that do something like: (cat header; cat mplayer_specific; cat footer) > mplayer.1 (cat header; cat mencoder_specific; cat footer) > mencoder.1 or a variation on this with more than three common and specific files interleaved? (i.e. first one with all the macro's et cetera) --Ivo
On Sat, Oct 23, 2004 at 06:44:41AM +0200, Ivo wrote:
On Saturday 23 October 2004 06:17, D Richard Felker III wrote:
i'm absolutely against xml for the man page unless the xml->man conversion can be done with no external dependencies whatsoever. it's bad enough to need some silly xml progs to generate the docs (but i don't read docs anymore anyway, or if i do i can just find them on the website). but not being able to read the manpage from cvs without having special doc tools installed would really suck!! (and it would lead to users not rtfm'ing!!! :/ )
I agree. No special tools.
Yeah, as mentioned I'm really against that...
Isn't it possible to have something like this: (i'm not a roff expert, so don't laugh)
Have a common header and footer, have an mplayer specific file and mencoder specific file and build scripts that do something like:
(cat header; cat mplayer_specific; cat footer) > mplayer.1 (cat header; cat mencoder_specific; cat footer) > mencoder.1
No, it is interleaved I think....
or a variation on this with more than three common and specific files interleaved? (i.e. first one with all the macro's et cetera)
Yeah, that's what I called a "sane" way of doing it... Regards Jonas
On Sat, 23 Oct 2004 00:17:33 -0400, D Richard Felker III <dalias@aerifal.cx> wrote:
On Fri, Oct 22, 2004 at 10:58:26PM +0200, Jonas Jermann wrote:
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.
i'm absolutely against xml for the man page unless the xml->man conversion can be done with no external dependencies whatsoever. it's bad enough to need some silly xml progs to generate the docs (but i don't read docs anymore anyway, or if i do i can just find them on the website). but not being able to read the manpage from cvs without having special doc tools installed would really suck!! (and it would lead to users not rtfm'ing!!! :/ )
rich
_______________________________________________ MPlayer-DOCS mailing list MPlayer-DOCS@mplayerhq.hu http://mplayerhq.hu/mailman/listinfo/mplayer-docs
how often does the user type "man -l $BUILD_ROOT/DOCS/man/en/mplayer.1", no, probably they type "man mplayer" and that is AFTER the install-procedure is done.
On Sat, Oct 23, 2004 at 03:14:48PM +0200, Carl Fûrstenberg wrote:
On Sat, 23 Oct 2004 00:17:33 -0400, D Richard Felker III <dalias@aerifal.cx> wrote:
On Fri, Oct 22, 2004 at 10:58:26PM +0200, Jonas Jermann wrote:
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.
i'm absolutely against xml for the man page unless the xml->man conversion can be done with no external dependencies whatsoever. it's bad enough to need some silly xml progs to generate the docs (but i don't read docs anymore anyway, or if i do i can just find them on the website). but not being able to read the manpage from cvs without having special doc tools installed would really suck!! (and it would lead to users not rtfm'ing!!! :/ )
rich how often does the user type "man -l $BUILD_ROOT/DOCS/man/en/mplayer.1", no, probably they type "man mplayer" and that is AFTER the install-procedure is done.
how does this have any relation to what i said?? if the install procedure depends on stupid xml tools which i don't have, it's not going to work!! rich
On Friday 22 October 2004 20:17, D Richard Felker III wrote:
iirc i was never in favor of it [splitting], 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, doing a 'slash'-search is really the fast way of rtfm-ing. A point is still that newer users might not really know what they are really looking for (or don't know the exact option/word/whatever). Scrolling down many many pages becomes annoying then. An idea that came to me was: a) show the raw structure of the manpage at the very beginning so that users can see directly, where the option/info they are looking for is (i.e. video output comes after audio output). I'm having in mind something similar to what can be found in DOCS/tech/manpage.txt b) create something like a bookmark, being a keyword that, when searching for it, points you to the beginng of the subsection you are looking for. Of course, this would have to be a word that doesn't exist yet. Personally, it isn't that much important to me personally. But I understand when newbies complain about a very long manpage. showing the structure and creating bookmarks would be an effort to simplify things somehow. Splitting up is no option for me.. Sebastian
participants (8)
-
Carl Fûrstenberg -
D Richard Felker III -
Dominik 'Rathann' Mierzejewski -
Ivo -
Jiri Heryan -
Jonas Jermann -
Sebastian Krämer -
Torinthiel