[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 <stsp_at_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
Received on 2010-10-30 22:19:13 CEST