allow state transitions back to 'waiting', as needed for cond vars

[nobug.git] / pipadoc

#!/bin/sh
#
#TIT pipadoc - Documentation extractor
#TIT =================================
#TIT Christian Thaeter <ct@pipapo.org>
#TIT
#LIC Copyright (C)              Pipapo Project
#LIC  2009,                     Christian Thaeter <ct@pipapo.org>
#LIC
#LIC This program is free software; you can redistribute it and/or modify
#LIC it under the terms of the GNU General Public License as published by
#LIC the Free Software Foundation; either version 2, or (at your option)
#LIC any later version.
#LIC
#LIC This program is distributed in the hope that it will be useful,
#LIC but WITHOUT ANY WARRANTY; without even the implied warranty of
#LIC MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#LIC GNU General Public License for more details.
#LIC
#LIC You should have received a copy of the GNU General Public License
#LIC along with this program; if not, contact Christian Thaeter <ct@pipapo.org>.
#LIC

#INT Embedding documentation in program source files often yields the problem that the
#INT structure of a program is most often not the optimal structure for the associated documentation.
#INT Still there are good reasons to maintain documentation together with the source right at the code
#INT which defines the documented functionality. Pipadoc addresses this problem by extracting
#INT special comments out of a source file and let one define rules how to bring the
#INT documentation into proper order.
#INT
#INT Pipadoc only extracts and reorders the text from it special comments, it never ever looks at the
#INT sourcecode or the text it extracts.
#INT
#INT This is somewhat similar to ``Literate Programming'' but it puts the emphasis back to the code.
#INT There is no need to extract the source from a literate source and in contrast to ``Literate Programming''
#INT the order of source and text is defined by the programmer and programming language constraints.
#INT
#INT Pipadoc is programming language and documentation system agnostic, all it requires is that
#INT the programming language has some line comments or block comments where one places doc statements
#INT on each block line (see xref:c-example[Example for C]).
#INT
#BAS [[BAS]]
#BAS Basic concepts
#BAS --------------
#BAS
#BAS NOTE: The following description uses the xref:ENV[default] settings for all examples.
#BAS
#BAS Pipadoc is controlled by special line comments.
#BAS
#DIR [[DIR]]
#DIR .Direct comments
#DIR Line comments immediately followed by a special documentation character (the underscore `_` by default)
#DIR are treated as direct comments. They will appear in order of appearance in the generated output.
#DIR These can be used to do some boilerplate stuff. Usually one wants to define a controlling document and
#DIR use this direct comments only there, since using them in different files might yield unexpected results
#DIR since the order then depends on the load order of the files.
#DIR ----
#DIR //_ This is a direct comment,
#DIR //_ it will appear just verbatim in the generated output
#DIR ----
#DIR
#KEY [[KEY]]
#KEY .Keys
#KEY A line comment immediately followed by a alphanumeric keyword (including the `_` underscore character)
#KEY is treated as key, all such keyed comments can later be placed in intended order with
#KEY a xref:SUB[substitution] comment.
#KEY ----
#KEY //example This text will later be inserted where one uses the `//=example` substitution.
#KEY //example All example lines are appended there in order even if they are defined at different
#KEY //example places or in different files
#KEY ----
#KEY
#KEY .Sorted Keys
#KEY A key can be appended with a dot `.` and a non-space string. This string will then be used to sort
#KEY these lines alphabetically. This can be used to create sorted indices and glossars, as well as reordering
#KEY paragraphs in stored under one primary key.
#KEY ----
#KEY //example.omega This is sorted after the next line
#KEY //example.alpha comes before the omega line above
#KEY ----
#KEY
#SUB [[SUB]]
#SUB .Substitutions
#SUB A line comment immediately followed by a special `substitution` character (the equal `=` sign by default)
#SUB followed by a xref:KEY[key] will be replaced by the text defined under that key. The rest of the line
#SUB is ignored and can be used as comment.
#SUB ----
#SUB //=example this will insert anything defined under `//example` here
#SUB ----
#SUB

#USE [[USE]]
#USE Documenting Files
#USE -----------------
#USE
#USE Usually one wants to write documentation in more or less smaller blocks which later shall be
#USE brought into proper order. The xref:SUB[substitutions] feature is the key for this. One writes
#USE his documentation blocks with comments which later get replaced by the right sorting key and
#USE finally brought into (alphabetical) stable-sort order. You might take a look at the pipadoc
#USE source itself to see it in action.
#USE

#ENV [[ENV]]
#ENV Environment Variables
#ENV ---------------------
#ENV
#ENV `COM`::
#ENV   Defines the line-comment character used in the source file.
#ENV   Defaults to `//` (C++/C99) if not set. Set this to `#` for shell
#ENV   like languages.
test "$COM" || COM='//'
#ENV `DOC`::
#ENV   The Documentation character which must follow a line comment to be recognized
#ENV   by pipadoc as documentation. Either one for local definitions or two for global
#ENV   definitions are used. Defaults to `_` and needs rarely to be changed.
test "$DOC" || DOC='_'
#ENV `SUB`::
#ENV   Substitution character. Defaults to `=` and rarely needs to be changed.
#ENV   See xref:SUB[substitutions] for details.
#ENV
test "$SUB" || SUB='='
#ENV [[ENVSXT]]
#ENV `SXT`::
#ENV   Section eXTention. Defaults to `.txt`.
#ENV   See xref:SXT[plaintext files] for details.
#ENV
test "$SXT" || SXT='.txt'

#SXT [[SXT]]
#SXT Documentation Only Files
#SXT ------------------------
#SXT
#SXT One can write documentation without the need of pipadoc special comments in files
#SXT which have a configured extension (see the xref:ENVSXT[SXT] environment variable).
#SXT Each line in such a file which does not have a pipadoc special comment is then implicitly
#SXT prepended with the line comment sequence and the basename of that file, for example
#SXT lines in a file 'foo.txt' will be treated as if they where written with `//foo ` in front of
#SXT them. Later xref:SUB[substitutions] can be used to organize the document.
#SXT When such a file has an ordinary pipadoc special comment line then this takes precedence over
#SXT the implicit commenting.
#SXT

#INV [[INV]]
#INV Invocation
#INV ----------
#INV
#INV Pipadoc is called with a list of files from which the documentation shall be extracted.
#INV The extracted documentation is piped to stdout. No other command line options are available.
#INV
#INV There are few xref:ENV[environment variables] to do basic configuration.
#INV

# here we go
awk -f /dev/fd/3 ${COM:+-v com="$COM"} ${DOC:+-v doc="$DOC"} ${SUB:+-v subs="$SUB"} ${SXT:+-v sxt="$SXT"} "$@" 3<<"EOF"

# Plaintext file handling
FILENAME ~ sxt "$" && $0 !~ "^" com {
  match(FILENAME, "/?([^/]*)" sxt "$", p)
  $0 = com p[1] " " $0
}

# Substitution
match($0, com subs "([[:alpha:]][[:alnum:]_]*)", s) {
  ++n
  subst[n] = s[1]
  next
}

# doc comment
match($0, com doc "([[:space:]](.*))?$", s) {
  ++n
  output[n] = s[2]
  next
}

# record all other comments which may be candidate comments
match($0, "(.*)" com "([[:alpha:]][[:alnum:]_]*)(([.]([^[:space:]]*)))?([[:space:]](.*))?", m) && m[1] !~ com {
  if (m[2] in maybe)
    maybe[m[2]] = maybe[m[2]] "\n.." m[5] " " m[7]
  else
    maybe[m[2]] = "." m[5] " " m[7]
  next
}

# finally output
END {
  for (i=1; i<=n; ++i)
    {
      if (i in output)
        print output[i]
      else
        {
          nelements = split(maybe[subst[i]], s, "\n[.]")
          split("", tosort)

          for (j=1; j <=nelements; ++j)
            {
              match(s[j], ".([^[:space:]]*) (.*)", entries)

              if ("." entries[1] in tosort)
                tosort["." entries[1]] = tosort["." entries[1]] "\n" entries[2]
              else
                tosort["." entries[1]] = entries[2]
            }

          elements = asorti(tosort, sorted)
          for (k = 1; k <= elements; ++k)
            {
              print tosort[sorted[k]]
            }
        }
    }
}
EOF

#Document structure:
#=TIT Titles and stuff
#=INT Introduction
#=BAS Basics
#=DIR Direct comments
#=KEY Key comments
#=SUB Substitutions
#=INV Invocation
#=USE Real usage
#=SXT Plain Documentation
#=ENV Environment variables
#_ Appendix
#_ --------
#=APP Appendix
#_ License
#_ -------
#_ [[LIC]]
#_ ....
#=LIC
#_ ....

# Examples and appendixes:
#USE .A small C99 Program
#USE [source,c]
#USE ----
#USE //intro This is the well known ``Hello World'' example
#USE //glos.helloworld A common program to show examples for programming language and tools
#USE
#USE //depends Only the Standard C library is needed
#USE #include <stdio.h>
#USE
#USE int main(int argc, char* argv[])
#USE {
#USE   //hello print the first commandline argument
#USE   //glos.argument the text you pass to the programm when calling it from the shell
#USE   //hello if no argument is given, then exit silently
#USE   if (argc > 1)
#USE     printf("Hello %s\n", argv[1]);
#USE   return 0;
#USE }
#USE
#USE // Now the document structure with substitutions:
#USE //_ Yet another 'Hello' program
#USE //_
#USE //=intro introduction first right after the title
#USE //intro
#USE //=hello The main documentation
#USE //_
#USE //_ Appendix
#USE //_ Dependencies:
#USE //=depends
#USE //_ Glossary
#USE //=glos glossary will be sorted
#USE ----
#USE
#USE Runnning this through pipadoc gives following output:
#USE ----
#USE Yet another 'Hello' program
#USE
#USE This is the well known ``Hello World'' example
#USE
#USE print the first commandline argument
#USE if no argument is given, then exit silently
#USE
#USE Appendix
#USE Dependencies:
#USE Only the Standard C library is needed
#USE Glossary
#USE the text you pass to the programm when calling it from the shell
#USE A common program to show examples for programming language and tools
#USE ----
#USE

#APP [[c-example]]
#APP
#APP .Using C block comments with pipadoc: +example.c+
#APP ----
#APP /*
#APP //_ this is a documentation line
#APP */
#APP ----
#APP use `pipadoc example.c` to process the documentation.
#APP