[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Monotone-devel] proposal for integrating manual and CLI help more close
From: |
Marcel van der Boom |
Subject: |
[Monotone-devel] proposal for integrating manual and CLI help more closely |
Date: |
Sun, 24 Jul 2005 09:54:43 +0200 |
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
- [Monotone-devel] proposal for integrating manual and CLI help more closely,
Marcel van der Boom <=