Re: [Monotone-devel] monotone man page
hend...@topoi.pooq.com writes: On Tue, Jun 29, 2010 at 10:29:12PM -0400, Aaron W. Hsu wrote: Hey Thomas, On Sat, 26 Jun 2010, Thomas Keller wrote: I am surprised that so few people have commented. Am I the only person who prefers man pages to info manuals? I actually have never used Monotone's info pages in their native form. I *hate* info pages, assuming you mean the ones read using the gnu info program. I've never used that. Reading info in Gnu Emacs is quite pleasant. Easier to do global search than in a typical web browser, and the hierarchical menuing is nice. A lot depends on the thought put into the document layout. monotone's doc is very good in this respect. -- -- Stephe ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] monotone man page
Stephen Leake stephen_le...@stephe-leake.org writes: The monotone Debian package installs the info file in the standard location; it could also install the man page. Yes, it does; Debian Policy mandates a man page for each executable. The current man page is from one of the first Debian package maintainers; it is now very out of date. It could also install the html version of the manual in a standard location; it doesn't do that at the moment. The man page should give URLs for both the remote and local HTML manuals. The package monotone-doc does install the HTML, PDF, info and plain text versions of the manual in the standard location /usr/share/doc/monotone-doc/*. -- Ludovic Brenta. ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] monotone man page
Hey Thomas, On Sat, 26 Jun 2010, Thomas Keller wrote: Am 21.06.10 00:47, schrieb Thomas Keller: I've just pushed some initial work to nvm.man-page to let monotone auto-generate its own man page [...] What do others think? Is it worthwhile to go down this route any further? I am surprised that so few people have commented. Am I the only person who prefers man pages to info manuals? I actually have never used Monotone's info pages in their native form. I haven't yet looked deeply into mandoc, but from what I've read I'm not totally convinced to use this dubbed superior format already if the old format simply works for now and is wildly accepted. Also I don't know what the status of mdoc is outside of the BSD world... Groff supports mdoc and an (man) macros. Some packages use mdoc and others use man. Man(7) is the predominent macro package for Linux man pages. That seems to be mostly a historical thing. Aaron W. Hsu ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] monotone man page
On Tue, Jun 29, 2010 at 10:29:12PM -0400, Aaron W. Hsu wrote: Hey Thomas, On Sat, 26 Jun 2010, Thomas Keller wrote: Am 21.06.10 00:47, schrieb Thomas Keller: I've just pushed some initial work to nvm.man-page to let monotone auto-generate its own man page [...] What do others think? Is it worthwhile to go down this route any further? I am surprised that so few people have commented. Am I the only person who prefers man pages to info manuals? I actually have never used Monotone's info pages in their native form. I have never used (and actually did not even know about the existence of) the info or man pages - `mtn --help blah`, with occasional reference to the online copy of the manual, has always worked for me. ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] monotone man page
Am 21.06.10 00:47, schrieb Thomas Keller: Hey there! I've just pushed some initial work to nvm.man-page to let monotone auto-generate its own man page [...] What do others think? Is it worthwhile to go down this route any further? I haven't yet looked deeply into mandoc, but from what I've read I'm not totally convinced to use this dubbed superior format already if the old format simply works for now and is wildly accepted. Also I don't know what the status of mdoc is outside of the BSD world... Thomas. -- GPG-Key 0x160D1092 | tommyd3...@jabber.ccc.de | http://thomaskeller.biz Please note that according to the EU law on data retention, information on every electronic information exchange might be retained for a period of six months or longer: http://www.vorratsdatenspeicherung.de/?lang=en signature.asc Description: OpenPGP digital signature ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] monotone man page
Am 22.06.2010 03:08, schrieb Aaron W. Hsu: On Sunday 20 June 2010 18:47:19 Thomas Keller wrote: Hey there! I've just pushed some initial work to nvm.man-page to let monotone auto-generate its own man page. If you compile this, a new hidden manpage command will be available, which dumps the command tree and a few additional information in (g)roff format, so you can then basically mtn manpage | groff -man -Tascii - | less to view the generated page. This is work-in-progress, as I'm fighting with some of groff's macros still (f.e. the indentation is not always correct). Also I need to tweak the output of our description methods a bit, because a couple of unwanted newlines are inserted as well, [this has been fixed] and I need a fancy / catchy DESCRIPTION for the program itself (proposals welcome!) - but basically it works. I haven't yet touched the build process part for that, so no, the man page will not be automatically generated / installed when you hit make install now... [this has been implemented in the meantime] I love this! I'm quite excited to get a man page with mtn. Cool :) Is there a chance that we could move to using mandoc instead of just the normal man pages? This will have positive benefits on the BSD systems, such as OpenBSD, which favors the mandoc system. I haven't heard of mandoc before, I have to admit its the first time I tried to write a man page at all. After looking at asciidoc and other similar projects which required too many tools in between or didn't produce the results I wanted, I sticked to the normal groff output. Could you elaborate a bit more about the positive benefits on these systems? Is there a reason that the documentation needs to be generated from the existing help documentation? Sometimes I find that it is nice to put much more information into a proper man page than what you get from the help command in monotone. Well, we had a dedicated man page years ago, but it was hard to take care of that and the manual, so it was not updated a lot. The main drive for this auto-generated man page is now to have the complete command set searchable / scannable and readable in one page. The main documentation source is of course the (info) manual we also supply, but if you're missing particular information in certain commands, then I'd love to see your patches for the CMD* macros :) - if the need arises, we could also add another (optional) parameter there which lets us describe things which then only pop up in the man page, but before that happens I'd rather see the command descriptions we have right now improved. The problem with all that is just that we do not have enough man power to do both things, manual and man page, by hand, given the fact that monotone is still very much in flux. Thomas. -- GPG-Key 0x160D1092 | tommyd3...@jabber.ccc.de | http://thomaskeller.biz Please note that according to the EU law on data retention, information on every electronic information exchange might be retained for a period of six months or longer: http://www.vorratsdatenspeicherung.de/?lang=en signature.asc Description: OpenPGP digital signature ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] monotone man page
On Tuesday 22 June 2010 03:39:31 Thomas Keller wrote: I haven't heard of mandoc before, I have to admit its the first time I tried to write a man page at all. After looking at asciidoc and other similar projects which required too many tools in between or didn't produce the results I wanted, I sticked to the normal groff output. Could you elaborate a bit more about the positive benefits on these systems? mandoc is basically a better man macro set for Roff that is used by the BSDs and I think that comes with Groff by default. See this link for a bit of story about what OpenBSD is doing: http://www.undeadly.org/cgi?action=articlesid=20100604082319 Is there a reason that the documentation needs to be generated from the existing help documentation? Sometimes I find that it is nice to put much more information into a proper man page than what you get from the help command in monotone. Well, we had a dedicated man page years ago, but it was hard to take care of that and the manual, so it was not updated a lot. The main drive for this auto-generated man page is now to have the complete command set searchable / scannable and readable in one page. The main documentation source is of course the (info) manual we also supply, but if you're missing particular information in certain commands, then I'd love to see your patches for the CMD* macros :) - if the need arises, we could also add another (optional) parameter there which lets us describe things which then only pop up in the man page, but before that happens I'd rather see the command descriptions we have right now improved. The problem with all that is just that we do not have enough man power to do both things, manual and man page, by hand, given the fact that monotone is still very much in flux. Hrm, maybe there is something I might be able to do to help that. I don't know. :-) I don't have the C++ know how to contribute directly to the code base, but documentation is something I do care a lot about, and I for one almost never use info manual pages, and use man pages as my primary means of documentation. I'll play around with some things if I get the time and maybe there will be something I can do to help the problem. Aaron W. Hsu signature.asc Description: This is a digitally signed message part. ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] monotone man page
On Sunday 20 June 2010 18:47:19 Thomas Keller wrote: Hey there! I've just pushed some initial work to nvm.man-page to let monotone auto-generate its own man page. If you compile this, a new hidden manpage command will be available, which dumps the command tree and a few additional information in (g)roff format, so you can then basically mtn manpage | groff -man -Tascii - | less to view the generated page. This is work-in-progress, as I'm fighting with some of groff's macros still (f.e. the indentation is not always correct). Also I need to tweak the output of our description methods a bit, because a couple of unwanted newlines are inserted as well, and I need a fancy / catchy DESCRIPTION for the program itself (proposals welcome!) - but basically it works. I haven't yet touched the build process part for that, so no, the man page will not be automatically generated / installed when you hit make install now... I love this! I'm quite excited to get a man page with mtn. Is there a chance that we could move to using mandoc instead of just the normal man pages? This will have positive benefits on the BSD systems, such as OpenBSD, which favors the mandoc system. Is there a reason that the documentation needs to be generated from the existing help documentation? Sometimes I find that it is nice to put much more information into a proper man page than what you get from the help command in monotone. Aaron W. Hsu signature.asc Description: This is a digitally signed message part. ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
[Monotone-devel] monotone man page
Hey there! I've just pushed some initial work to nvm.man-page to let monotone auto-generate its own man page. If you compile this, a new hidden manpage command will be available, which dumps the command tree and a few additional information in (g)roff format, so you can then basically mtn manpage | groff -man -Tascii - | less to view the generated page. This is work-in-progress, as I'm fighting with some of groff's macros still (f.e. the indentation is not always correct). Also I need to tweak the output of our description methods a bit, because a couple of unwanted newlines are inserted as well, and I need a fancy / catchy DESCRIPTION for the program itself (proposals welcome!) - but basically it works. I haven't yet touched the build process part for that, so no, the man page will not be automatically generated / installed when you hit make install now... Thomas. -- GPG-Key 0x160D1092 | tommyd3...@jabber.ccc.de | http://thomaskeller.biz Please note that according to the EU law on data retention, information on every electronic information exchange might be retained for a period of six months or longer: http://www.vorratsdatenspeicherung.de/?lang=en signature.asc Description: OpenPGP digital signature ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
