[Monotone-devel] proposal for integrating manual and CLI help more closely

[Marcel van der Boom]

I've been playing around a bit to get access to the monotone command  
syntax in a more integrated way than having the manual open and  
comparing things with what is issued by the command line. I've come  
up with a little prototype which roughly works as follows:

1. each mtn command gets a separate texinfo file
2. from that file a 'man page' is constructed automatically
3. mtn help command (instead of the --help option) is used to access  
that collection of man pages
4. the --help option displays the synopsis only with a mention to use  
mtn help 'command' to get detailed info

The basis of this prototype (just the extra parts, not a changed  
monotone for this) is available at:
http://davinci.hsdev.com/monotone/txi2man-proto.tar.gz if people are  
interested.

The idea is to have 1 place where commands are documented (the  
texinfo manual) and generate CLI help information from that file.  
This information should of course also be used in the manual itself.
I've taken the texinfo2man.c file from the gnu indent program as a  
basis to generate a man page out of a texinfo file, using a man  
template. The man page is generated with something like: texinfo2man  
man_template.in texinfo.file > command.1 which can then be further  
processed if needed.

What this would give us is that the manual and CLI are always in sync  
and that the help information is more closely at the point where you  
do the work.

Some more details:

The man_template.in file looks something like:

.TH "@NAME@" 1
.SH "NAME"
@NAME@ - @NAMEDESC@

@MANPAGE@

In it's simplest form. The @THINGS@ are placeholders to be replaced  
by (transformed) content from the texinfo file

The beginning of mt.diff.texi could look like this for example:

@c !BEGIN NAME
monotone diff
@c !END NAME

@c !BEGIN NAMEDESC
show differences between working directory and database
@c !END NAMEDESC

@c !BEGIN MANPAGE
@section SYNOPSIS
@table @command
@item
monotone diff
@item
monotone diff --context
@item
monotone diff --external address@hidden
@item
monotone diff @var{pathname...}
@item
monotone diff address@hidden
@item
monotone diff address@hidden @var{pathname...}
@item
monotone diff address@hidden address@hidden
@item
monotone diff address@hidden address@hidden @var 
{pathname...}
@end table

@section DESCRIPTION
These commands print out GNU ``unified diff format'' textual difference
...
...

Thoughts?

marcel

--
Marcel van der Boom
HS-Development BV               --   http://www.hsdev.com
So! webapplicatie framework  --   http://make-it-so.info

smime.p7s
Description: S/MIME cryptographic signature