[Pkg-ocaml-maint-commits] [SCM] camlmix packaging branch, master, updated. debian/1.3.0-3-7-gf588587

Tue May 28 09:38:10 UTC 2013

The following commit has been merged in the master branch:
commit cf8089e281f19bf975a34ff6472f78f4b922ee4d
Author: Hendrik Tews <hendrik at askra.de>
Date:   Tue May 28 11:19:56 2013 +0200

    rewrite man page

diff --git a/debian/camlmix.1 b/debian/camlmix.1
index 32869eb..06e26eb 100644
--- a/debian/camlmix.1
+++ b/debian/camlmix.1
@@ -1,173 +1,251 @@
-.TH CAMLMIX 1 "December 2, 2010" "camlmix User Manual"
+.\" groff -man -Tascii prooftree.1
+.\" ==========================================================================
+.\" ============= Synopsis ===================================================
+.\" ==========================================================================
+.TH CAMLMIX 1 "May 2013" CAMLMIX "User Manuals"
 .SH NAME
-.PP
-camlmix - preprocessor which converts text with embedded OCaml.
+camlmix \- preprocessor which converts text with embedded OCaml
 .SH SYNOPSIS
-.PP
-camlmix [options] file1 file2 \&... fileN
-.PP
-A temporary file \[lq]fileN.ml\[rq] is created and then executed with
-ocaml.
+.B camlmix \fR[\fIOptions...\fR] \fIfiles\fR...
+.\" ==========================================================================
+.\" ============= Description ================================================
+.\" ==========================================================================
 .SH DESCRIPTION
-.SS General rules
-.PP
-Text between ## and ## is considered as a block of code.
-A block of code is normally some OCaml code.
-It can be any kind of toplevel expressions such as definitions or
-application of printing functions:
-.IP
-.nf
-\f[C]
-This\ is\ ocaml\ version\ ##\ print\ Sys.ocaml\\_version\ ##
-\f[]
-.fi
-.PP
-If it starts with = the OCaml code is interpreted as an expression of
-type string that will printed like the rest of the text:
-.PP
-This is ocaml version ##= Sys.ocaml_version ##
-.PP
-The document blocks are printed by default on stdout using the
-\[lq]print\[rq] function.
-For ## to be printed, ### should be used.
-.PP
-White space introduced by OCaml can be controlled by ##.
-and .## symbols:
-.IP
-.nf
-\f[C]
-\ \ ##.\ causes\ any\ white\ space\ to\ the\ left\ of\ the\ symbol
-\ \ \ \ \ \ to\ be\ omitted\ from\ the\ output.\ Similarly
-\ \ .##\ causes\ any\ white\ space\ followed\ by\ one\ newline
-\ \ \ \ \ \ to\ be\ omitted\ from\ the\ output.
-\f[]
-.fi
-.SS \ Directives
-.PP
-Blocks of code that start with the \@ character (possibly preceded by
-spaces) are directives for Camlmix.
-The following directives are available:
-.IP
-.nf
-\f[C]
-include\ "somefile.mlx";\ (*\ inserts\ a\ camlmix\ file\ *)
-skip;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ (*\ ignores\ the\ next\ block\ of\ text\ *)
-\f[]
-.fi
-.PP
-e.g.:
-.IP
-.nf
-\f[C]
-Hello\ ##\ \@include\ "world.mlx";\ skip\ .##\ ##\ let\ x\ =\ 123\ ##!
-\f[]
-.fi
-.SS Conversion into a \[lq]render\[rq] function for dynamic rendering
-.PP
-The -fun option, used in combination with -c and often -co produces an
-OCaml source file which provides a function with the following
-signature:
-.PP
-val render : ?print:(string -> unit) -> ANYTYPE -> unit
-.PP
-where ANYTYPE is the type the \[lq]param\[rq] object which is available
-in the template.
-\[lq]param\[rq] can be used to pass runtime arguments, such as CGI
-parameters if you are serving dynamic web pages.
-The \[lq]print\[rq] function is used to set the initial value of
-Camlmix.printer (see below) and should be used if you want to be able to
-put the output into some other container than stdout.
-It's default value is:
-.PP
-fun s -> print_string s; flush stdout
-.SS Advanced usage
-.PP
-The OCaml program that is generated from the Camlmix files first defines
-a module called Camlmix.
-This module contains several variables that are updated automatically
-and may be used explicitly by the user.
-.IP
-.nf
-\f[C]
-module\ Camlmix\ :
-\ \ sig
-\ \ \ \ val\ source\ :\ string\ ref
-\ \ \ \ val\ line\ \ \ :\ int\ ref
-\ \ \ \ val\ char\ \ \ :\ int\ ref
-\ \ \ \ \ \ \ \ (*\ source,\ line\ and\ char\ refer\ to\ the\ location\ of\ the
-\ \ \ \ \ \ \ \ \ \ \ first\ character\ of\ the\ current\ block\ in\ its\ source\ file
-\ \ \ \ \ \ \ \ \ \ \ (source\ file,\ line\ number\ starting\ from\ 1,\ position\ in
-\ \ \ \ \ \ \ \ \ \ \ the\ line\ starting\ from\ 1).\ They\ are\ updated
-\ \ \ \ \ \ \ \ \ \ \ automatically\ at\ the\ beginning\ of\ each\ (code\ or\ text)
-\ \ \ \ \ \ \ \ \ \ \ block.\ *)
-
-\ \ \ \ val\ printer\ :\ (string\ ->\ unit)\ ref
-\ \ \ \ \ \ \ \ (*\ the\ function\ that\ prints\ text\ blocks.\ It\ is\ initialized
-\ \ \ \ \ \ \ \ \ \ \ with\ the\ "print"\ function\ *)
-
-\ \ \ \ val\ print_with\ :\ (string\ ->\ unit)\ ->\ unit
-\ \ \ \ \ \ \ \ (*\ print_with\ f\ prints\ the\ next\ block\ of\ text\ using\ f
-\ \ \ \ \ \ \ \ \ \ \ instead\ of\ the\ current\ printer.\ Its\ behavior\ is
-\ \ \ \ \ \ \ \ \ \ \ undefined\ if\ it\ is\ called\ several\ times\ in\ the\ same
-\ \ \ \ \ \ \ \ \ \ \ OCaml\ block.\ *)
-
-\ \ \ \ val\ print_if\ :\ bool\ ->\ unit
-\ \ \ \ \ \ \ \ (*\ print_if\ cond\ prints\ the\ next\ block\ of\ text\ only
-\ \ \ \ \ \ \ \ \ \ \ if\ cond\ is\ true.\ It\ uses\ print_with.\ *)
-\ \ end
-\f[]
-.fi
+.B camlmix
+processes text templates with embedded 
+.B OCaml
+code to generate text again. From one or several input files it
+generates an
+.B OCaml
+text generation program and executes this to obtain the result.
+Using option
+.I -fun
+one can also convert the text template into an 
+.B OCaml
+text generation function.
+.\"
+.\" ==========================================================================
+.\" ================ Options =================================================
+.\" ==========================================================================
+.\"
 .SH OPTIONS
+.\" ===================== -o =================================================
+.TP
+.B "-o output"
+write the generated text into file 
+.I output
+.\" ===================== -c =================================================
 .TP
 .B -c
-only generate the .ml file
-.RS
-.RE
+Only generate the text generation program, don't execute it. 
+By default, the program is called 
+.I lastfile.ml
+when
+.I lastfile
+is the last file argument.
+.\" ===================== -co ================================================
 .TP
-.B -co \f[C]filename\f[]
-specify a name for the .ml file or \[lq]-\[rq] for stdout
-.RS
-.RE
+.B "-co file"
+specify the name of the text generation program
+.\" ===================== -fun ===============================================
 .TP
-.B -fun
-make it the body of a function named \[lq]render\[rq], using a single
-argument named \[lq]param\[rq]
-.RS
-.RE
+.B "-fun"
+generate 
+.B OCaml
+code for text generation function from the input (see
+.B ADVANCED USAGE
+below)
+.\" ===================== -e =================================================
 .TP
-.B -e \f[C]ocaml\f[]
-specify ocaml executable
-.RS
-.RE
+.B "-e ocamlc"
+set the name of the OCaml executable
+.\" ===================== -clean =============================================
+.TP
+.B "-clean"
+remove the text generation program after execution
+.\" ===================== -insert ============================================
+.TP
+.B "-insert ocaml_code"
+insert
+.I ocaml_code
+at the beginning of the text generation program
+.\" ===================== -remix =============================================
+.TP
+.B "-remix"
+try a conversion to the camlremix syntax
+.\" ===================== -a ================================================
 .TP
-.B -o \f[C]file\f[]
-specify an output file
+.B "-version"
+print version and exit
+.\" ===================== -help ================================================
+.TP
+.B "-help | --help"
+print help and exit (this man page was written from the output of
+.I -help\fR)
+.\"
+.\" ==========================================================================
+.\" ================ Basic Usage =============================================
+.\" ==========================================================================
+.\"
+.SH BASIC USAGE
+.\" ================ General rules ===========================================
+Text enclosed with
+.I ## 
+markers is considered as a block of 
+.B OCaml
+code. It can be any kind of toplevel expressions such as
+definitions or application of printing functions:
+.P
 .RS
+This is ocaml version ## print Sys.ocaml\_version ##
 .RE
-.TP
-.B -clean
-remove the temporary .ml file after execution
+.P
+If the
+.B OCaml
+code starts with
+.I = 
+then it is interpreted as an expression of type string that will
+printed like the rest of the text:
+.P
 .RS
+This is ocaml version ##= Sys.ocaml_version ##
 .RE
+.P
+The text block are printed together with the evaluated
+.B OCaml
+pieces using the 
+.I print
+function. Include
+.I ###
+to print
+.I ##\fR.
+.\" ==========================================================================
+.P
+White space can be controlled with
+.I ##.
+and
+.I .##\fR:
+.TP
+.B ##. 
+don't print white space occurring on the left
 .TP
-.B -insert \f[I]ocaml code\f[]
-insert this code first
+.B .## 
+don't print white space up to and including the first newline,
+following to the right.
+.\"
+.\" ==========================================================================
+.\" ================ Advanced Usage ==========================================
+.\" ==========================================================================
+.\"
+.SH ADVANCED USAGE
+.\" ================ Directives ==============================================
+.SS Directives
+Blocks of code that start with the
+.I @
+character (possibly preceded by spaces) are directives for
+Camlmix. There are two directives. 
+.I include
+inserts a camlmix file, and
+.I skip
+skips the next block. For instance
+.P
 .RS
+Hello ## @include "world.mlx"; skip .## ## let x = 123 ##!
 .RE
-.TP
-.B -remix
-try a conversion to the camlremix syntax
+.P
+.\" ================ text gen function =======================================
+.SS Conversion into a text generation function for dynamic rendering
+The 
+.I -fun
+option, used in combination with
+.I -c 
+and often
+.I -co
+produces an
+.B OCaml
+source file which provides a function
+.I render
+with the following signature:
+.P
 .RS
+val render : ?print:(string -> unit) -> 'a -> unit
 .RE
-.TP
-.B -version
-prints the version of Camlmix and exits
+.P
+The polymorphic argument is called
+.I param
+in the generated code and can be used to pass runtime arguments
+into the 
+.I render
+function. The
+.I print
+function is used to set the initial value of Camlmix.printer (see
+below). It's default value is:
+.P
 .RS
+       fun s -> print_string s; flush stdout
 .RE
+.P
+.\" ================ Runtime hooks ==========================================
+.SS Runtime hooks
+The text generation program, which
+.B camlmix
+generates, contains a module
+.I Camlmix
+at the beginning, which can be used in code blocks. This module
+has the following signature.
+.P
+.RS 4
+module \fBCamlmix\fR : sig
+.RS 4
 .TP
-.B -help|--help
-Display this list of options
-.RS
+val \fBsource\fR : string ref
+.TP
+val \fBline\fR : int ref
+.TP
+val \fBchar\fR : int ref
+Location of the first character of the current block in its
+source file. Line and character numbers count from 1. These
+references are updated by
+.B camlmix
+at the beginning of each block.
+.TP
+val \fBprinter\fR : (string -> unit) ref 
+function for printing text blocks
+.TP
+val \fBprint_with\fR : (string -> unit) -> unit
+.I print_with f
+causes the next text block to be printed with
+.I f
+instead of the current printer. Its behavior is undefined if it
+is called several times in the same code block.
+.TP
+val \fBprint_if\fR : bool -> unit
+.I print_if cond 
+prints the next text block only if condition
+.I cond 
+is true. It uses 
+.I print_with
+internally.
+.P
+.RE
+end
 .RE
-.SH AUTHORS
-Sylvain Le Gall.
+.P
+.\"
+.\" ==========================================================================
+.\" ================ SEE ALSO ================================================
+.\" ==========================================================================
+.\"
+.SH SEE ALSO
+.TP
+The \fBcamlmix\fR web page, \fIhttp://mjambon.com/camlmix/\fR
+.\"
+.\" ==========================================================================
+.\" ================ Author ==================================================
+.\" ==========================================================================
+.\"
+.SH AUTHOR
+This manual page was written by Sylvain Le Gall
+<gildor at debian.org> and Hendrik Tews <hendrik at askra.de>,
+specifically for the Debian project (and may be used by others).
+
diff --git a/debian/camlmix.mkd b/debian/camlmix.mkd
index f6b217c..26e7fd8 100644
--- a/debian/camlmix.mkd
+++ b/debian/camlmix.mkd
@@ -1,3 +1,7 @@
+% these are the old sources from which the man page was generated with 
+% debian/camlmix.1: debian/camlmix.mkd
+% 	pandoc -s -w man $^ -o $@
+%
 % CAMLMIX(1) camlmix User Manual
 % Sylvain Le Gall
 % December 2, 2010
diff --git a/debian/changelog b/debian/changelog
index b46ecee..17c434e 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -12,8 +12,9 @@ camlmix (1.3.1-1) unstable; urgency=low
     adapt rules and dependencies 
   * bump standards version and debhelper compat level
   * add patch fix-lintian-spelling-error to fix a spelling error
+  * rewrite man page from scatch
 
- -- Hendrik Tews <hendrik at askra.de>  Mon, 27 May 2013 23:49:26 +0200
+ -- Hendrik Tews <hendrik at askra.de>  Tue, 28 May 2013 11:18:37 +0200
 
 camlmix (1.3.0-3) unstable; urgency=low
 
diff --git a/debian/rules b/debian/rules
index a32bc3f..1ea34b6 100755
--- a/debian/rules
+++ b/debian/rules
@@ -26,7 +26,3 @@ endif
 override_dh_auto_install:
 	mkdir -p '$(DESTDIR)/usr/bin'
 	make install 'PREFIX=$(DESTDIR)/usr'
-
-# debian/camlmix.1: debian/camlmix.mkd
-# 	pandoc -s -w man $^ -o $@
-

-- 
camlmix packaging

