[Docutils-checkins] r4782 - in trunk/sandbox/manpage-writer: README.txt rst2man.txt

[<gr...@us...>]

Author: grubert
Date: 2006-10-22 17:40:09 +0200 (Sun, 22 Oct 2006)
New Revision: 4782

Added:
   trunk/sandbox/manpage-writer/rst2man.txt
Modified:
   trunk/sandbox/manpage-writer/README.txt
Log:
More details on man page structure and a man page for the tool.


Modified: trunk/sandbox/manpage-writer/README.txt
===================================================================
--- trunk/sandbox/manpage-writer/README.txt	2006-10-21 21:53:46 UTC (rev 4781)
+++ trunk/sandbox/manpage-writer/README.txt	2006-10-22 15:40:09 UTC (rev 4782)
@@ -17,6 +17,39 @@
 Module information
 ''''''''''''''''''
 
+man pages look like ::
+       
+   man(1)     Man Pager Utils     man(1)
+       
+   NAME
+       man - an interface to the on-line reference manuals
+       
+   SYNOPSIS
+       man [-c|-w|-tZT device] [-adhu7V] [-m system[,...]] [-L locale]
+     
+in roff formatting ::
+     
+     .TH man 1 "14 May 2001" "2.3.19" "Manual pager utils"
+     .SH NAME
+     man \- an interface to the on-line reference manuals
+     .SH SYNOPSIS
+     .\" The general command line
+     .B man
+     .RB [\| \-c \||\| \-w \||\| \-tZT
+     .IR device \|]
+
+This means we have 
+
+* a title "man" 
+* a subtitle "an interface to the on-line reference manuals"
+* a section "1"
+* a group "Manual pager utils"
+* a date "14 May 2001"
+* a version "2.3.19"
+
+
+
+
 Problems
 ''''''''
 
@@ -63,6 +96,9 @@
        man - program to view ...
 
 * line ends around email or web addresses in texts.
+  How to distinguish something is inline or not ?
+
+  
 * too much line ends.
 * Is one rst-document one manpage section or might there be more sections
   contained.
@@ -76,6 +112,7 @@
 
 * writers/manpage.py:
 
+  - 2006-10-22: less empty lines
   - 2006-10-21: from sandbox/grubert, better option list handling,
                 definition list handling.
 

Added: trunk/sandbox/manpage-writer/rst2man.txt
===================================================================
--- trunk/sandbox/manpage-writer/rst2man.txt	2006-10-21 21:53:46 UTC (rev 4781)
+++ trunk/sandbox/manpage-writer/rst2man.txt	2006-10-22 15:40:09 UTC (rev 4782)
@@ -0,0 +1,76 @@
+=========
+ rst2man
+=========
+
+---------------------------------------------
+generate unix manpages from reStructured text
+---------------------------------------------
+
+:Author: gr...@us...
+:Date:   2006-10-22
+:Copyright: public domain
+:Version: 0.1
+:Manual section: 1
+:Manual group: text processing
+
+.. TODO: authors and author with name <email>
+
+SYNOPSIS
+========
+
+  rst2man.py inputfile outputfile
+
+DESCRIPTION
+===========
+
+rst2man transforms a reStructured text document into a unix man page.
+
+In theory any valid reStructured text document should be processable,
+in reality this is
+
+* a goal, that is not met yet
+* a goal that might never be met, because only few constructs are
+  used in man pages *and* because the common text file does not adhere
+  to man page requirements. 
+  
+  For example a unix man page belongs into a numbered section, 1 is 
+  user commands, 8 contains administrator commands and the headlines
+  of all manpages are collected into a database, queryable with the
+  programm ``apropos``, therefore the headline should contain a short
+  text describing into which group this command belongs.
+
+  These informations are collected from title, subtitle and the
+  docinfo, see this document as an example.
+
+OPTIONS
+=======
+
+--config=<file>         Read configuration settings from <file>, if it exists.
+--version, -V           Show this program's version number and exit.
+--help, -h              Show this help message and exit.
+
+And a lot more standard docutils options.
+
+FILES
+=====
+
+None yet.
+
+SEE ALSO
+========
+
+`docutils <http://docutils.sourceforge.net>`__
+
+and ``man man``
+
+BUGS
+====
+
+1. Format options are included as they are required. 
+2. bullet lists
+3. number lists
+
+
+Discussion is still open.
+
+


Property changes on: trunk/sandbox/manpage-writer/rst2man.txt
___________________________________________________________________
Name: svn:keywords
   + Author Date Id Revision
Name: svn:eol-style
   + native