[Hyrum K. Wright] > Would it be possible to define a simple markup format, and then just > put these strings in a text file and process that, similar to what we > do with our sql statements now. Is there a markup format which > already exists which would suit this purpose?
I have to say I kinda like the git approach. 'git merge --help' literally spawns 'man git-merge', which is a full-featured manpage, including a references section and all that. For a tool that has no ambitions to work on anything but a Unix platform, it seems like a pretty good approach. I suppose it would be problematic for typical Windows installs of the command line binaries. Maintaining real man pages is an idea I've toyed with in my brain for quite some time. It should even be possible to dump them to plain text, at release roll time, for the benefit of platforms that are nroff-deprived. These would end up in a Subversion 'library' directory alongside the binaries, shared libraries, message catalogs and whatnot, and the command-line binaries would launch 'more' or 'notepad' or something, to show a file. Automatically selecting the correct localized file is, unfortunately, something 'man' already does pretty well, that one would have to reinvent for man-less platforms. (I do have to say I have a bias against docbook, like most other uses of XML, as it's quite verbose and clunky for text editing. nroff format may seem quaint, but it's actually quite editable once you get used to it.) I don't know how localization of manpages usually work, but a lot of projects ship piles of translated manpages. I assume the pages in each language are just separately maintained, with translators taking cues from the updates to the original version. > On Sat, Oct 30, 2010 at 8:28 AM, Stefan Sperling <s...@elego.de> wrote: > > I'd like to keep the texts short enough so they can still be > > embedded as C strings into the binary. Being constrained is a good > > thing because I don't want the help texts to end up replacing the > > book. I don't understand why it would be a bad thing to replace the book, at least for usage, semantic information, and examples. The book, or something like it, is clearly still needed to communicate concepts and best practices. Peter
