lipsum.1

.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "lipsum 1"
.TH lipsum 1 "2017-09-17" "2015" "Christian Lindig"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
lipsum \- a simple literate programming utility
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBlipsum\fR \fBtangle\fR [\fB\-f\fR \fIfmt\fR] \fIchunk\fR [\fIfile.lp\fR]
.PP
\&\fBlipsum\fR \fBexpand\fR [\fB\-f\fR \fIfmt\fR] \fIglob\fR [\fIfile.lp\fR]
.PP
\&\fBlipsum\fR \fBformats\fR
.PP
\&\fBlipsum\fR \fBroots\fR [\fIfile.lp\fR]
.PP
\&\fBlipsum\fR \fBcheck\fR [\fIfile.lp\fR]
.PP
\&\fBlipsum\fR \fBchunks\fR [\fIfile.lp\fR]
.PP
\&\fBlipsum\fR \fBundefined\fR [\fIfile.lp\fR]
.PP
\&\fBlipsum\fR \fBweave\fR [\fIfile.lp\fR]
.PP
\&\fBlipsum\fR \fBcopyright\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBLipsum\fR is a tool for literate programming in the tradition of NoWeb
and Sweave. A literate program is a file that contains both
documentation and source code which are separated by a lightweight
markup. \fBlipsum\fR's primary task is to extract the source from a
literate program to make it available for compilation and execution.
This is traditionally called \fItangling\fR. \fBLipsum\fR is language agnostic
and can be used with almost any programming language and documentation
syntax.
.SH "COMMANDS"
.IX Header "COMMANDS"
The first command line parameter identifies a command (like \fBtangle\fR or
\&\fBroots\fR), which is followed by options, parameters, and file names.
A command that expects a named file for input will typically read input
from \fIstdin\fR when no file name is given. Output of a command generally goes
to \fIstdout\fR. All commands accept an option \fB\-\-help\fR to show online
help.
.IP "\fBtangle\fR [\fB\-f\fR \fIfmt\fR] \fIchunk\fR [\fIfile.lp\fR]" 4
.IX Item "tangle [-f fmt] chunk [file.lp]"
Extract \fIchunk\fR from \fIfile.lp\fR and emit it to \fIstdout\fR. Commands
\&\fBchunks\fR and \fBroots\fR list the available chunks. The extracted code
optionally includes references to  original source code locations in
\&\fIfile.lp\fR. For a list of available formats, use \fBformats\fR.
.IP "\fBformats\fR" 4
.IX Item "formats"
Emit the list of available source code position formats. The best known
format is \f(CW\*(C`cpp\*(C'\fR as it is used by the C preprocessor \fIcpp\fR\|(1) and works for
many languages that use \f(CW\*(C`#\*(C'\fR to start a comment.
.IP "\fBexpand\fR [\fB\-f\fR \fIfmt\fR] \fIglob\fR [\fIfile.lp\fR]" 4
.IX Item "expand [-f fmt] glob [file.lp]"
Extract each root code chunk matching shell pattern \fIglob\fR to a file of
the same name using format \fIfmt\fR. This is a quick way extract all code
chunks in one go into individual files. On the shell command line, you have
to quote the \fIglob\fR pattern to avoid the shell expanding it:
.Sp
.Vb 1
\&    $ lipsum \-f cpp \*(Aq*.[ch]\*(Aq file.lp
.Ve
.Sp
This will expand all chunks matching `*.c` or `*.h` using the \fIcpp\fR\|(1)
format for back references into \fIfile.lp\fR.
.Sp
Note that pattern \f(CW\*(C`*\*(C'\fR does not match a \f(CW\*(C`/\*(C'\fR and hence \f(CW\*(C`*.c\*(C'\fR does not
match \f(CW\*(C`a/b.c\*(C'\fR.
.IP "\fBroots\fR [\fIfile.lp\fR]" 4
.IX Item "roots [file.lp]"
List the name of all root code chunks, one per line. A root chunk is
a chunk that is not part of another code chunk.
.IP "\fBundefined\fR [\fIfile.lp\fR]" 4
.IX Item "undefined [file.lp]"
List code chunks that are referenced but not defined, one per line.
.IP "\fBchunks\fR [\fIfile.lp\fR]" 4
.IX Item "chunks [file.lp]"
List the name of all code chunks, one per line.
.IP "\fBweave\fR [\fIfile.lp\fR]" 4
.IX Item "weave [file.lp]"
Emit \fIfile.lp\fR  with code chunks indented by 4 spaces. This makes the
output suitable for Markdown provided the documentation is already in
Markdown syntax.
.IP "\fBcopyright\fR" 4
.IX Item "copyright"
Emit the copyright notice and license to \fIstdout\fR.
.SH "FILE FORMAT"
.IX Header "FILE FORMAT"
A literate program as it is understood by \fBlipsum\fR is a sequence of
documentation and code chunks. Code chunks are named and may include
references to other code chunks. Command \fBchunks\fR lists all available
chunks in a file.  Below is a simple example:
.PP
.Vb 5
\&    Echo prints each command line argument on a line by itself. This 
\&    documentation chunk extends until the beginning of the named code
\&    chunk @<<echo.c>> below. Here I had to use @ to escape the meaning
\&    of @<< because otherwise it would have denoted a reference to a named 
\&    code chunk.
\&
\&    <<echo.c>>=
\&    /* <<copyright>> */
\&    #include <stdio.h>
\&
\&    int main(int argc, char** argv)
\&    {
\&            int i;
\&            for (i=0; i<argc; i++)
\&                    puts(argv[i]);
\&            return 0;
\&    }
\&
\&    @ By keeping the copyright notice in a chunk by itself it is easy to
\&    include it in several files. A documenation starts with an @ followed
\&    by a space and extends until the beginning of the next chunk. Unless
\&    the @ is at the beginnung at the line it has no special meaning.
\&
\&    <<copyright>>=
\&    This code is in the public domain.
.Ve
.PP
Documentation is introduced by an \f(CW\*(C`@\*(C'\fR at the beginning of a line, followed
by a space or a newline. Code chunks are named and introduced by \f(CW\*(C`<<\*(C'\fR and
>>=. A name can span several words but must not include a newline. A
reference to a chunk is enclosed by \f(CW\*(C`<<\*(C'\fR and \f(CW\*(C`\*(C'\fR>>. A chunk extends until
the beginning of the next chunk or the end of input. The first chunk in
a file is by default a documentation chunk.
.PP
A code chunk can be extended:
.PP
.Vb 2
\&    <<copyright>>=
\&    This code is part of the documentation for Lipsum
.Ve
.PP
When the \f(CW\*(C`copyright\*(C'\fR chunk is expanded, the two chunks are concatenated
and hence the copyright chunk expands to:
.PP
.Vb 2
\&    /* This code is in the public domain.
\&    This code is part of the documentation for Lipsum. */
.Ve
.PP
When a chunk is extracted with command \fBexpand\fR (traditionally called
tangling), the code is emitted to \fIstdout\fR and all references are resolved
by emitting the referenced chunks during the process. A code chunk must not
include references to itself or any of the chunks where it is referenced.
.SH "QUOTING"
.IX Header "QUOTING"
Since a lipsum file uses @, <<, >>, and >>= for markup, a mechanism is
needed to include these in documentation and code chunks, as well as chunk
names. The general mechanism is to prefix strings with \f(CW\*(C`@\*(C'\fR to escape their
meaning as markup.
.PP
Below are situations where escaping is important.
.ie n .IP """@"" in code" 4
.el .IP "\f(CW@\fR in code" 4
.IX Item "@ in code"
The \f(CW\*(C`@\*(C'\fR character only needs to be escaped when it is the first character
in a line. Escape it as \f(CW\*(C`@@\*(C'\fR.
.ie n .IP """<<"" in code or documentation" 4
.el .IP "\f(CW<<\fR in code or documentation" 4
.IX Item "<< in code or documentation"
Any occurrence of \f(CW\*(C`<<\*(C'\fR in code or documentation that does not indicate a
named chunk needs to be escaped as \f(CW\*(C`@<<\*(C'\fR.
.ie n .IP """@<<"" in code" 4
.el .IP "\f(CW@<<\fR in code" 4
.IX Item "@<< in code"
Escape \f(CW\*(C`@<<\*(C'\fR as \f(CW\*(C`@@<<\*(C'\fR.
.ie n .IP """@"" in chunk names" 4
.el .IP "\f(CW@\fR in chunk names" 4
.IX Item "@ in chunk names"
Escape \f(CW\*(C`@\*(C'\fR as \f(CW\*(C`@@\*(C'\fR.
.ie n .IP """<<"", and "">>="" in chunk names" 4
.el .IP "\f(CW<<\fR, and \f(CW>>=\fR in chunk names" 4
.IX Item "<<, and >>= in chunk names"
Escape any of the above strings by prefixing them with \f(CW\*(C`@\*(C'\fR.
.ie n .IP """@<<"", ""@>>"", ""@>>="" in chunk names" 4
.el .IP "\f(CW@<<\fR, \f(CW@>>\fR, \f(CW@>>=\fR in chunk names" 4
.IX Item "@<<, @>>, @>>= in chunk names"
Escape any of them by prefixing them with another \f(CW\*(C`@\*(C'\fR.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP """no such chunk""" 4
.el .IP "\f(CWno such chunk\fR" 4
.IX Item "no such chunk"
The named chunk does not exist. Use commands \fBroots\fR or \fBchunks\fR to list 
existing chunks.
.ie n .IP """chunk is part of a cylcle""" 4
.el .IP "\f(CWchunk is part of a cylcle\fR" 4
.IX Item "chunk is part of a cylcle"
A chunk must not include itself directly or indirectly as it would expand
to an infinite document. A chunk was found to violate this.
.ie n .IP """unexpeced newline in chunk name""" 4
.el .IP "\f(CWunexpeced newline in chunk name\fR" 4
.IX Item "unexpeced newline in chunk name"
A chunk name must not contain a newline character. The error is most likely
caused by << inside code that looks to the scanner like the beginning of
a chunk name. Prefix it with @ like in @<< to escape it.
.ie n .IP """unexpeced end of file in chunk name""" 4
.el .IP "\f(CWunexpeced end of file in chunk name\fR" 4
.IX Item "unexpeced end of file in chunk name"
The scanner encountered the end of input after reading << and assuming 
that this marks the beginning of a chunk name. Prefix it with @ 
like in  @<< to signal that it is not the beginning of a chunk name or 
close the chunk name properly with >> or >>=.
.SH "UNICODE"
.IX Header "UNICODE"
Lipsum is not unicode aware but should work with \s-1UTF8\s0 files regardless. If
you have suggestions how to make Lipsum unicode aware the author would be
interested to hear about them.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
The \fBlipsum\fR utility returns 0 on success and a positive number if an
error occurs.
.SH "EXIT CODE"
.IX Header "EXIT CODE"
\&\fBLipusm\fR exits with 0 on success and a positive number otherwise.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fInotangle\fR\|(1), \fIcpp\fR\|(1), http://daringfireball.net/projects/markdown/
.SH "AUTHOR"
.IX Header "AUTHOR"
Written by Christian Lindig <lindig@gmail.com>. The source code is
available from https://github.com/lindig/lipsum.git
.SH "LICENSE"
.IX Header "LICENSE"
See command \fBcopyright\fR for how to display the copyright notice and
license.