Re: [Monotone-devel] Re: monotone man page
Am 30.06.2010 07:58, schrieb Gour: > On Sat, 26 Jun 2010 23:13:59 +0200 >>> "Thomas" == Thomas Keller wrote: > > Thomas> What do others think? Is it worthwhile to go down this route > Thomas> any further? > > Have you thought about using Pandoc? > > (http://johnmacfarlane.net/pandoc/) > > It enables you to use one source (e.g. markdown/reST) and then convert > to plethora of formats. > > From the homepage: "Pandoc can read markdown and (subsets of) > reStructuredText, HTML, and LaTeX, and it can write plain text, > markdown, reStructuredText, HTML, LaTeX, ConTeXt, PDF, RTF, DocBook > XML, OpenDocument XML, ODT, GNU Texinfo, MediaWiki markup, groff man > pages, and S5 HTML slide shows. PDF output (via LaTeX) is also > supported with the included markdown2pdf wrapper script." > > > Here I plan to use it to write markdown (or reST) and then generate > user manual docs via sphinx and gt PDF as well. > > You can generate Texinfo which is presently used by monotone. > > (I do not like Asciidoc since it involves DocBook toolchain...) Well, if I can avoid any other tool, then this should be preferred. After all the solely reason for this work is to generate a man page, I don't want texinfo, PDF, HTML output or whatsoever from it. We have a great online manual, that should be enough. What I meant with or rather hoped to get feedback for when I asked "is it worthwhile to go down this route any further?" was if the _information_ in their current form as they're provided by the current mechanism is suitable for a decent man page. A few things come into my mind here: a) command / group ordering cannot be ordered in a custom way, therefor API commands may come before the really important stuff b) its not possible (yet) to add additional information for certain commands or groups which should only popup in the man page c) I'm still missing a well-written description - nobody has provided any so far Anything else? 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
[Monotone-devel] Re: monotone man page
On Wed, 30 Jun 2010 09:17:11 +0200 >> "Thomas" == Thomas Keller wrote: Thomas> Well, if I can avoid any other tool, then this should be Thomas> preferred. After all the solely reason for this work is to Thomas> generate a man page, I don't want texinfo, PDF, HTML output or Thomas> whatsoever from it. We have a great online manual, that should Thomas> be enough. That's OK, but I suggested pandoc in order to have one-source for different outputs, i.e. to have same help text for command reference available in man page as in online manual. Thomas> What I meant with or rather hoped to get feedback for when I Thomas> asked "is it worthwhile to go down this route any further?" was Thomas> if the _information_ in their current form as they're provided Thomas> by the current mechanism is suitable for a decent man page. See above. ;) Sincerely, Gour -- Gour | Hlapicina, Croatia | GPG key: F96FF5F6 signature.asc Description: PGP signature ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
[Monotone-devel] Re: monotone man page
Aaron W. Hsu 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. Oh, I do actively hate info pages and (almost) never use them. Sometimes, in case of dire need, I resort to pinfo to use them, that at least has the sort-of-known-to-me hotkey set of lynx. So, I'm happy if monotone grows a manpage, but OTOH using "mtn help " is easier to read, since it's already in the correct point of the (etherwise long) text. But of course the man page could explain more stuff than commands, and that wouldn't have an easy place in the executable itself. -- Lapo Luchini - http://lapo.it/ “Never worry about theory as long as the machinery does what it's supposed to do.” (Robert A. Heinlein, "Waldo & Magic, Inc.", 1950) ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] Re: is monotone for me?
Yup that is an understatement - one of the reasons why I was attracted to the project... When the biggest cause of corruption seems to be faulty RAID hardware then you know that you are onto a winner. I did some tests, with the aide of one of the developers, to simulate corruption (I was worried about faulty desktop disks corrupting other databases on sync). It was damn difficult to get it past the local mtn process without it detecting it and then pretty much impossible (I never got it to sync with a corrupted db - but very difficult to prove a negative etc) to get it past the sync stage :-). hend...@topoi.pooq.com wrote: On Mon, Jun 28, 2010 at 10:41:50PM +0100, CooSoft Support wrote: It has proved to be totally reliable That's for me is the most important thing about monotone, trumping all other considerations. The monotone developers are more paranoid about data loss than I am. -- hendrik. ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] monotone man page
Thomas Keller writes: > I've just pushed some initial work to nvm.man-page to let monotone > auto-generate its own man page. In my opinion, there are two uses for a man page: - to give a summary of the arguments and options, all in one place, so you can search for things - to point to the more complete manual somewhere else. mtn is lacking these two things at the moment. But the command line help tends to be very good, and I know about the info manual (I read it in Emacs), so I don't miss the man page. It makes perfect sense to generate the manpage from the mtn help information. Adding the reference to the local info and online html manuals can simply be hardcoded in the C++ code for the 'mtn manpage' command. Note that many man pages refer to a manual, but don't give precise instructions on how to access it, which is just frustrating. So be sure to include a URL for the online manual, and the full path to the actual info file on the local disk. Hmm, the later assumes you can deduce the info install path from the mtn executable install path; I guess that's not true. So each distribution will have to customize that. Maybe there needs to be a hook to run the user's favorite info viewer, or at least to give the full path to the info file. On distributions with standard locations for man and info files, it might be enough to just say "in the standard locations for this distribution". But it's better to give a precise reference if possible; when someone is learning a new distribution, they need all the help they can get :). > 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 > 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... Man pages are not much use if not installed, but that's also not hard to do once the man page is ready. On the other hand, the installation location is distribution dependent. On Win32, there is no 'man' command, so we probably don't need to bother with man for that distribution. On the other hand, if someone has a MinGW toolset with man, they might want it. Cygwin has a normal 'man', and a standard location for info files; the Cygwin monotone package installs the info file properly, and could install the man page also. The monotone Debian package installs the info file in the standard location; it could also install the man page. 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. -- -- Stephe ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] Re: monotone man page
Thomas Keller writes: > What I meant with or rather hoped to get feedback for when I asked "is > it worthwhile to go down this route any further?" was if the > _information_ in their current form as they're provided by the current > mechanism is suitable for a decent man page. A few things come into my > mind here: > > a) command / group ordering cannot be ordered in a custom way, therefor > API commands may come before the really important stuff This is annoying, but not really important. The important point of a man page is to be able to search thru all the options/commands at once, looking for something you could not find from the command line. > b) its not possible (yet) to add additional information for certain > commands or groups which should only popup in the man page That's fine; the texinfo manual is for that sort of thing. > c) I'm still missing a well-written description - nobody has provided > any so far By "description" you mean the first paragraph of the man page? Just say "world's best distributed configuration management system"; nothing else is needed :). Seriously, mtn is too complex to describe in one paragraph; better to say "mtn is a distributed configuration management system", and then refer to the texinfo manual. -- -- Stephe ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] Re: monotone man page
Gour writes: > On Wed, 30 Jun 2010 09:17:11 +0200 >>> "Thomas" == Thomas Keller wrote: > > Thomas> Well, if I can avoid any other tool, then this should be > Thomas> preferred. After all the solely reason for this work is to > Thomas> generate a man page, I don't want texinfo, PDF, HTML output or > Thomas> whatsoever from it. We have a great online manual, that should > Thomas> be enough. > > That's OK, but I suggested pandoc in order to have one-source for > different outputs, i.e. to have same help text for command reference > available in man page as in online manual. In your proposal, how does the command line help text get merged into the mtn executable? Given the current state of mtn documentation, the right way to have the command line help be the same as the texinfo manual is to have 'mtn manpage' (or another similar command) dump a texinfo fragment for each command, and have monotone.texi include those fragments at the appropriate places. That might be worth it; the texinfo manual tends to leave out arguments and options. -- -- 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 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] Re: monotone man page
Am 30.06.2010 14:53, schrieb Stephen Leake: > Thomas Keller writes: >> c) I'm still missing a well-written description - nobody has provided >> any so far > > By "description" you mean the first paragraph of the man page? Just say > "world's best distributed configuration management system"; nothing else > is needed :). > > Seriously, mtn is too complex to describe in one paragraph; better to > say "mtn is a distributed configuration management system", and then > refer to the texinfo manual. What mtn basically is - "a distributed version control system" - is already printed earlier. I'm not heading for a complex description, more for some advertisement. git f.e. says: "Git is a fast, scalable, distributed revision control system with an unusually rich command set that provides both high-level operations and full access to internals." and gives pointers to other informational resources. What about this: "monotone is a highly reliable, very customizable distributed version control system that provides lightweight branches, history-sensitive merging and a flexible trust setup. monotone has an easy-to-learn command set and comes with a rich interface for scripting purposes." Too many buzzwords? I'm open for suggestions! 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
[Monotone-devel] Re: monotone man page
Thomas Keller wrote: > "monotone is a highly reliable, very customizable distributed version > control system that provides lightweight branches, history-sensitive > merging and a flexible trust setup. monotone has an easy-to-learn > command set and comes with a rich interface for scripting purposes." > > Too many buzzwords? I'm open for suggestions! Seems nice enough to me. Maybe "comes with a rich interface for scripting purposes and thorough documentation"? -- Lapo Luchini - http://lapo.it/ ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
[Monotone-devel] Re: monotone man page
Stephen Leake wrote: > The monotone Debian package installs the info file in the standard FreeBSD Port (and thus package) install the info page and HTML manual in the standard locations and could install man page as well: /usr/local/info/monotone.info /usr/local/share/doc/monotone/NEWS /usr/local/share/doc/monotone/UPGRADE /usr/local/share/doc/monotone/figures/* /usr/local/share/doc/monotone/images/* /usr/local/share/doc/monotone/monotone.html /usr/local/share/doc/monotone/texinfo.css BTW: it also needs for those NOT TO be installed on request, and right now I'm messing with Makefile.in to remove 'em from the install target. -- Lapo Luchini - http://lapo.it/ ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
Re: [Monotone-devel] Re: monotone man page
Am 30.06.10 16:46, schrieb Lapo Luchini: > Thomas Keller wrote: >> "monotone is a highly reliable, very customizable distributed version >> control system that provides lightweight branches, history-sensitive >> merging and a flexible trust setup. monotone has an easy-to-learn >> command set and comes with a rich interface for scripting purposes." >> >> Too many buzzwords? I'm open for suggestions! > > Seems nice enough to me. > > Maybe "comes with a rich interface for scripting purposes and thorough > documentation"? Added in cc0353da7add2c33f296b93d2bbd5fcde2208a0e. 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
[Monotone-devel] Re: monotone man page
On Wed, 30 Jun 2010 09:01:15 -0400 >> "Stephen" == wrote: Stephen> In your proposal, how does the command line help text get Stephen> merged into the mtn executable? That I do not know not being at all familiar with mtn build system and/or structure. Stephen> Given the current state of mtn documentation, the right way to Stephen> have the command line help be the same as the texinfo manual Stephen> is to have 'mtn manpage' (or another similar command) dump a Stephen> texinfo fragment for each command, and have monotone.texi Stephen> include those fragments at the appropriate places. I can only speak based on the experience with darcs where the whole manual is part of the source (literate programming) and man page as well as darcs' help command display the same command reference text which is otherwise present in the complete user manual under Reference chapter. Sincerely, Gour -- Gour | Hlapicina, Croatia | GPG key: F96FF5F6 signature.asc Description: PGP signature ___ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel
