Re: simplifying & enhancing kde manpages
Achim Bohnet writes: > I'm not sure if it's okay to c&p qts debug.html in a (L)GPL manpage. in a GPL manpage: yes, otherwise: probably not, but it's not like they're going to sue you over c&p'ing some stuff out of their docs.. cheers domi
Re: simplifying & enhancing kde manpages
On Thursday 15 April 2004 17:42, Nathaniel W. Turner wrote: > On Tue, 27 Jan 2004 22:17:34 +0100 Achim Bohnet wrote: > > My idea now was now to create a kde-options(?) manpage^Wsgml that describes > > the generic kde and qt options (later maybe in more detail). From all > > other manpages just use a reference to this manpage. > > Have you made any progress on this? > > This really does seem like the Right Way to document these options -- after > all, they are not provided by the applications themselves, but by kdelibs and > qt; it makes sense therefor, to put the documentation in the libs packages as > well. If KDE adds (or worse, removes) an option to the common KDE options, > do we really want to have to update every individual application's manpage? > Would the individual app maintainers even notice something this subtle? > > Anyway, nobody seemed to think this was a bad idea, so I guess I don't need > to > try so hard to convince you. =) > > I'm willing to help with this, but of course I don't want to duplicate any > effort. Hi Nathaniel, Sorry for the late responce. I've not done much. Got sidetracked by docbook2man UTF-8 brain damage, sgml, license problem ... :( I'm MIA most of the time this year :( Please feel free to take over. I've attached 2 manpages Karolina send to me and a modified copy of one of Chris's manpages with some additions from qt3/doc/html/debug.html and kdecore/html/classKCmdLineArgs.html I'm not sure if it's okay to c&p qts debug.html in a (L)GPL manpage. Achim > > Cheers, > nate -- To me vi is Zen. To use vi is to practice zen. Every command is a koan. Profound to the user, unintelligible to the uninitiated. You discover truth everytime you use it. -- [EMAIL PROTECTED] --- Begin Message --- tisdagen den 27 januari 2004 22.17 you wrote: > My idea now was now to create a > kde-options(?) manpage^Wsgml that describes the generic kde and > qt options (later maybe in more detail). From all other manpages > just use a reference to this manpage.If possible one could > even create templates in kdelibs-dev that are included and allow to > change these generic parts of each kde manpage at a central > place. I once did this and man-pages to almost all KDE binaries in debian for KDE 3.1 Attached is my version, if it can be of any help. Karolina kdelibs.kdeenviron Description: Troff document kdelibs.kdeqtoptions Description: Troff document --- End Message --- --- Begin Message --- torsdagen den 29 januari 2004 15.21 you wrote: > Hi Karolina, > > great, especially the environment manpage!! This was too only wish/todo > list. IGood, that I updated to sarge last night instead of working on the > manpages ;) 'll convert them to sgml and merge with stuff I already have. > Btw. there's not copyright notice. Is LGPL okay? That's ok. Karolina --- End Message --- manpage.1'. You may view the manual page with: `docbook-to-man manpage.sgml | nroff -man | less'. A typical entry in a Makefile or Makefile.am is: manpage.1: manpage.sgml docbook-to-man $< > $@ The docbook-to-man binary is found in the docbook-to-man package. Please remember that if you create the nroff version in one of the debian/rules file targets (such as build), you will need to include docbook-to-man in your Build-Depends control field. --> Chris"> Cheney"> January 28, 2004"> 1"> [EMAIL PROTECTED]"> KDE-OPTIONS"> Debian"> GNU"> ]> &dhemail; &dhfirstname; &dhsurname; 2002 &dhusername; &dhdate; &dhucpackage; &dhsection; &dhpackage; standard command line options supported by almost every kde application DESCRIPTION Describes the standard options supported by almost every KDE application. The command line options of KDE programs follow the usual GNU command line syntax, with long options starting with two dashes (`-'). The list of standard command line options is included below. GENERIC OPTIONS --author Show author information. --help Show help about options. --help-all Show all options. --help-kde Show KDE specific options. --help-qt Show Qt specific options. --license Show license information. -v, --version Show version information. STANDARD QT OPTIONS --bg, --background color Sets the default background color and an application palette (light and dark shades are calculated).
Re: simplifying & enhancing kde manpages
Nathaniel W Turner writes: > On Tue, 27 Jan 2004 22:17:34 +0100 Achim Bohnet wrote: >> My idea now was now to create a kde-options(?) manpage^Wsgml that >> describes the generic kde and qt options (later maybe in more >> detail). From all other manpages just use a reference to this >> manpage. > Have you made any progress on this? > This really does seem like the Right Way to document these options > -- after all, they are not provided by the applications themselves, > but by kdelibs and qt; it makes sense therefor, to put the > documentation in the libs packages as well. If KDE adds (or worse, > removes) an option to the common KDE options, do we really want to > have to update every individual application's manpage? Would the > individual app maintainers even notice something this subtle? > Anyway, nobody seemed to think this was a bad idea, so I guess I > don't need to try so hard to convince you. =) > I'm willing to help with this, but of course I don't want to > duplicate any effort. Since I'm not sure I already told you about this: Everyone working on kde man pages in general might have a look at the kdemangen.pl script in kdesdk/scripts. The output is fairly good, and probably very useful as the base for the real manpages. Also the kde-options manpage could perhaps be based on its output ? cheers domi
Re: simplifying & enhancing kde manpages
On Tue, 27 Jan 2004 22:17:34 +0100 Achim Bohnet wrote: > My idea now was now to create a kde-options(?) manpage^Wsgml that describes > the generic kde and qt options (later maybe in more detail). From all > other manpages just use a reference to this manpage. Have you made any progress on this? This really does seem like the Right Way to document these options -- after all, they are not provided by the applications themselves, but by kdelibs and qt; it makes sense therefor, to put the documentation in the libs packages as well. If KDE adds (or worse, removes) an option to the common KDE options, do we really want to have to update every individual application's manpage? Would the individual app maintainers even notice something this subtle? Anyway, nobody seemed to think this was a bad idea, so I guess I don't need to try so hard to convince you. =) I'm willing to help with this, but of course I don't want to duplicate any effort. Cheers, nate -- Make sure your vote will count. http://www.verifiedvoting.org/
Re: simplifying & enhancing kde manpages
On Wed, Jan 28, 2004 at 11:43:55AM +0100, Achim Bohnet wrote: > On Tuesday 27 January 2004 23:03, Dominique Devriese wrote: > > Achim Bohnet writes: > > > > > My idea now was now to create a kde-options(?) manpage^Wsgml that > > > describes the generic kde and qt options (later maybe in more > > > detail). From all other manpages just use a reference to this > > > manpage. If possible one could even create templates in kdelibs-dev > > > that are included and allow to change these generic parts of each > > > kde manpage at a central place. > > > > > Does this sound reasonable? > > > > It does to me. It's great that you are going to work on the KDE > > program manpages. Especially for command line utilities like dcop*, > > this would be really useful. > > Thx, Ben, Chris, Dominique for the encouraging answers. > I've started last night and created kde-options from kde-config, > augmenting (well cut and paste) it with descriptions from the qt > and kdelibs docs. Then realized, that kdelibs > is LGPL and and I'm not sure if QT GPL is compatible with the > '...with no Invariant Sections, no Front-Cover Texts and no Back-Cover > Texts.' > addition Chris used in his manpages. > > So it looks like I have to wait a bit and use my own words. Maybe > I also ask some KDE developers for an okay to an LGPL -> GPL > transition when I find much useful material in the kdelibs docs. > Or Chris, in this case would you give your okay to put kde-config > under the LGPL? > > I'm definitly not an good english writer and modifying c&p gives > certainly a better result that me formulating the text. Hmm I didn't even realize it was under GFDL, yea I am going to relicense all mine under LGPL. Thanks for bringing that point up. Chris signature.asc Description: Digital signature
Re: simplifying & enhancing kde manpages
On Tuesday 27 January 2004 23:03, Dominique Devriese wrote: > Achim Bohnet writes: > > > My idea now was now to create a kde-options(?) manpage^Wsgml that > > describes the generic kde and qt options (later maybe in more > > detail). From all other manpages just use a reference to this > > manpage. If possible one could even create templates in kdelibs-dev > > that are included and allow to change these generic parts of each > > kde manpage at a central place. > > > Does this sound reasonable? > > It does to me. It's great that you are going to work on the KDE > program manpages. Especially for command line utilities like dcop*, > this would be really useful. Thx, Ben, Chris, Dominique for the encouraging answers. I've started last night and created kde-options from kde-config, augmenting (well cut and paste) it with descriptions from the qt and kdelibs docs. Then realized, that kdelibs is LGPL and and I'm not sure if QT GPL is compatible with the '...with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.' addition Chris used in his manpages. So it looks like I have to wait a bit and use my own words. Maybe I also ask some KDE developers for an okay to an LGPL -> GPL transition when I find much useful material in the kdelibs docs. Or Chris, in this case would you give your okay to put kde-config under the LGPL? I'm definitly not an good english writer and modifying c&p gives certainly a better result that me formulating the text. > > > Btw. is there a script that generates from a --help ouput an sgml > > manpage skeleton? > > I wrote a script that generates nroff manpage code directly once. > It's currently in kdesdk/scripts/kdemangen.pl. Ah, thx for the info. I'll look into it, if it's easy to change to create sgml, when I'll add manpages to kdebluetooth pkg (currently fighting with --enable-final ;). Achim > > cheers > domi -- To me vi is Zen. To use vi is to practice zen. Every command is a koan. Profound to the user, unintelligible to the uninitiated. You discover truth everytime you use it. -- [EMAIL PROTECTED]
Re: simplifying & enhancing kde manpages
On Tue, Jan 27, 2004 at 11:03:20PM +0100, Dominique Devriese wrote: > > Btw. is there a script that generates from a --help ouput an sgml > > manpage skeleton? > > I wrote a script that generates nroff manpage code directly once. > It's currently in kdesdk/scripts/kdemangen.pl. Using nroff might acutally be a better idea than using docbook, at least compared to using the docbook-to-man utility since its a bit odd. I don't remember the specific issues I saw with it anymore but I recall it being hard to get it to format the same was as normal nroff pages. Chris signature.asc Description: Digital signature
Re: simplifying & enhancing kde manpages
On Tue, Jan 27, 2004 at 10:17:34PM +0100, Achim Bohnet wrote: > Hi, > > looking at the kde man pages I note that the qt and kde standrd options > are more or less listed and described. Often they hide the actual > funtionality of the program. There's a good reason for --help-{qt,kde,all} > and not just --help listing everything ;) > > My idea now was now to create a > kde-options(?) manpage^Wsgml that describes the generic kde and > qt options (later maybe in more detail). From all other manpages > just use a reference to this manpage.If possible one could > even create templates in kdelibs-dev that are included and allow to > change these generic parts of each kde manpage at a central > place. > > Does this sound reasonable? Sounds good to me. > Anyone knows a kde manpage that has a complete or maybe more > in depth description of the standard options? Otherwise I would > use kde-config.sgml as a start for kde-options. Not sure about this... > Btw. is there a script that generates from a --help ouput an sgml > manpage skeleton? I just manually did it for the manpages that are out there so far. There is an example sgml manpage skeleton with nothing in it in the dh-make package. Chris signature.asc Description: Digital signature
Re: simplifying & enhancing kde manpages
Achim Bohnet writes: > My idea now was now to create a kde-options(?) manpage^Wsgml that > describes the generic kde and qt options (later maybe in more > detail). From all other manpages just use a reference to this > manpage. If possible one could even create templates in kdelibs-dev > that are included and allow to change these generic parts of each > kde manpage at a central place. > Does this sound reasonable? It does to me. It's great that you are going to work on the KDE program manpages. Especially for command line utilities like dcop*, this would be really useful. > Btw. is there a script that generates from a --help ouput an sgml > manpage skeleton? I wrote a script that generates nroff manpage code directly once. It's currently in kdesdk/scripts/kdemangen.pl. cheers domi
Re: simplifying & enhancing kde manpages
> My idea now was now to create a > kde-options(?) manpage^Wsgml that describes the generic kde and > qt options (later maybe in more detail). From all other manpages > just use a reference to this manpage. FWIW, I think this is an excellent idea. Ben.