Provided by: tcllib_1.21+dfsg-1_all bug

NAME

       doctools_lang_intro - doctools language introduction

DESCRIPTION

       This  document  is  an  informal introduction to version 1 of the doctools markup language
       based on a multitude of  examples.  After  reading  this  a  writer  should  be  ready  to
       understand  the  two  parts of the formal specification, i.e. the doctools language syntax
       specification and the doctools language command reference.

   FUNDAMENTALS
       In the broadest terms possible the doctools markup language is LaTeX-like, instead of like
       SGML  and  similar  languages.  A  document written in this language consists primarily of
       text, with markup commands embedded into it.

       Each markup command is a Tcl command surrounded by a matching pair of [ and ].  Inside  of
       these  delimiters  the  usual rules for a Tcl command apply with regard to word quotation,
       nested commands, continuation lines, etc. I.e.

                ... [list_begin enumerated] ...

                ... [call [cmd foo] \
                        [arg bar]] ...

                ... [term {complex concept}] ...

                ... [opt "[arg key] [arg value]"] ...

   BASIC STRUCTURE
       The most simple document which can be written in doctools is

                  [manpage_begin NAME SECTION VERSION]
              [see_also doctools_intro]
              [see_also doctools_lang_cmdref]
              [see_also doctools_lang_faq]
              [see_also doctools_lang_syntax]
              [keywords {doctools commands}]
              [keywords {doctools language}]
              [keywords {doctools markup}]
              [keywords {doctools syntax}]
              [keywords markup]
              [keywords {semantic markup}]
                  [description]
                  [vset CATEGORY doctools]
              [include ../common-text/feedback.inc]
              [manpage_end]

       This also shows us that all doctools documents are split into two parts,  the  header  and
       the  body.  Everything  coming  before [description] belongs to the header, and everything
       coming after belongs to the body, with the whole document bracketed by the  two  manpage_*
       commands. Before and after these opening and closing commands we have only whitespace.

       In  the  remainder  of  this  section we will discuss only the contents of the header, the
       structure of the body will be discussed in the section Text structure.

       The header section can be empty, and otherwise may contain only an arbitrary  sequence  of
       the four so-called header commands, plus whitespace. These commands are

       titledesc

       moddesc

       require

       copyright

       They provide, through their arguments, additional information about the document, like its
       title, the title of the  larger  group  the  document  belongs  to  (if  applicable),  the
       requirements of the documented packages (if applicable), and copyright assignments. All of
       them can occur multiple times, including none, and they can be used in any order.  However
       for  titledesc  and  moddesc  only  the  last  occurrence  is taken. For the other two the
       specified information is accumulated, in the given order.  Regular  text  is  not  allowed
       within the header.

       Given the above a less minimal example of a document is

              [manpage_begin NAME SECTION VERSION]
              [copyright {YEAR AUTHOR}]
              [titledesc TITLE]
              [moddesc   MODULE_TITLE]
              [require   PACKAGE VERSION]
              [require   PACKAGE]
              [description]
              [manpage_end]

       Remember that the whitespace is optional. The document

                  [manpage_begin NAME SECTION VERSION]
                  [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
                  [require PACKAGE VERSION][require PACKAGE][description]
                  [vset CATEGORY doctools]
              [include ../common-text/feedback.inc]
              [manpage_end]

       has the same meaning as the example before.

       On  the  other  hand,  if  whitespace  is  present it consists not only of any sequence of
       characters containing the space character, horizontal and vertical tabs, carriage  return,
       and  newline,  but  it  may  contain  comment  markup  as well, in the form of the comment
       command.

              [comment { ... }]
              [manpage_begin NAME SECTION VERSION]
              [copyright {YEAR AUTHOR}]
              [titledesc TITLE]
              [moddesc   MODULE_TITLE][comment { ... }]
              [require   PACKAGE VERSION]
              [require   PACKAGE]
              [description]
              [manpage_end]
              [comment { ... }]

   ADVANCED STRUCTURE
       In the simple examples of the last section we fudged a bit regarding the  markup  actually
       allowed to be used before the manpage_begin command opening the document.

       Instead  of only whitespace the two templating commands include and vset are also allowed,
       to enable the writer to either set and/or import configuration settings  relevant  to  the
       document. I.e. it is possible to write

              [include FILE]
              [vset VAR VALUE]
              [manpage_begin NAME SECTION VERSION]
              [description]
              [manpage_end]

       Even  more  important,  these  two commands are allowed anywhere where a markup command is
       allowed, without regard for any other structure. I.e. for example in the header as well.

              [manpage_begin NAME SECTION VERSION]
              [include FILE]
              [vset VAR VALUE]
              [description]
              [manpage_end]

       The only restriction include has to obey is that the contents of the included file must be
       valid at the place of the inclusion. I.e. a file included before manpage_begin may contain
       only the templating commands vset and include, a file included in the header  may  contain
       only header commands, etc.

   TEXT STRUCTURE
       The  body  of  the  document  consists  mainly  of  text,  possibly  split  into sections,
       subsections, and paragraphs, with parts marked up to highlight various semantic categories
       of text, and additional structure through the use of examples and (nested) lists.

       This section explains the high-level structural commands, with everything else deferred to
       the following sections.

       The simplest way of structuring the body is through the introduction  of  paragraphs.  The
       command  for  doing  so  is  para.  Each  occurrence  of  this command closes the previous
       paragraph and automatically opens the next. The first paragraph is automatically opened at
       the  beginning  of  the  body,  by  description.  In  the  same  manner the last paragraph
       automatically ends at manpage_end.

              [manpage_begin NAME SECTION VERSION]
              [description]
               ...
              [para]
               ...
              [para]
               ...
              [manpage_end]

       Empty paragraphs are ignored.

       A structure coarser than paragraphs are sections,  which  allow  the  writer  to  split  a
       document  into  larger,  and  labeled,  pieces.  The command for doing so is section. Each
       occurrence of this command closes the previous section and automatically opens  the  next,
       including  its first paragraph. The first section is automatically opened at the beginning
       of the body, by description (This section is labeled "DESCRIPTION"). In  the  same  manner
       the last section automatically ends at manpage_end.

       Empty sections are not ignored. We are free to (not) use paragraphs within sections.

              [manpage_begin NAME SECTION VERSION]
              [description]
               ...
              [section {Section A}]
               ...
              [para]
               ...
              [section {Section B}]
               ...
              [manpage_end]

       Between  sections  and paragraphs we have subsections, to split sections.  The command for
       doing so is subsection. Each occurrence of this command closes the previous subsection and
       automatically opens the next, including its first paragraph. A subsection is automatically
       opened at the beginning of the body, by description, and at the beginning of each section.
       In the same manner the last subsection automatically ends at manpage_end.

       Empty subsections are not ignored. We are free to (not) use paragraphs within subsections.

              [manpage_begin NAME SECTION VERSION]
              [description]
               ...
              [section {Section A}]
               ...
              [subsection {Sub 1}]
               ...
              [para]
               ...
              [subsection {Sub 2}]
               ...
              [section {Section B}]
               ...
              [manpage_end]

   TEXT MARKUP
       Having  handled  the  overall  structure a writer can impose on the document we now take a
       closer at the text in a paragraph.

       While most often this is just the unadorned content of the document we do have  situations
       where  we  wish  to  highlight  parts  of  it as some type of thing or other, like command
       arguments, command names, concepts, uris, etc.

       For this we have a series of markup commands which take the text  to  highlight  as  their
       single  argument.  It should be noted that while their predominant use is the highlighting
       of parts of a paragraph they can also be used to  mark  up  the  arguments  of  list  item
       commands, and of other markup commands.

       The commands available to us are

       arg    Its argument is a the name of a command argument.

       class  Its argument is a class name.

       cmd    Its argument is a command name (Tcl command).

       const  Its argument is a constant.

       emph   General, non-semantic emphasis.

       file   Its argument is a filename / path.

       fun    Its argument is a function name.

       method Its argument is a method name

       namespace
              Its argument is namespace name.

       opt    Its argument is some optional syntax element.

       option Its argument is a command line switch / widget option.

       package
              Its argument is a package name.

       sectref
              Its argument is the title of a section or subsection, i.e. a section reference.

       syscmd Its argument is a command name (external, system command).

       term   Its argument is a concept, or general terminology.

       type   Its argument is a type name.

       uri    Its  argument is a uniform resource identifier, i.e an external reference. A second
              argument can be used to specify an explicit label for the reference in question.

       usage  The arguments describe the syntax of a Tcl command.

       var    Its argument is a variable.

       widget Its argument is a widget name.

       The example demonstrating the use of text markup is an excerpt from the doctools  language
       command  reference,  with  some  highlighting added.  It shows their use within a block of
       text, as the arguments of a list item command (call), and our ability to nest them.

                ...
                [call [cmd arg_def] [arg type] [arg name] [opt [arg mode]]]

                Text structure. List element. Argument list. Automatically closes the
                previous list element. Specifies the data-[arg type] of the described
                argument of a command, its [arg name] and its i/o-[arg mode]. The
                latter is optional.
                ...

   ESCAPES
       Beyond the 20 commands for simple markup shown in the previous section we  have  two  more
       available  which are technically simple markup.  However their function is not the marking
       up of phrases as specific types of things, but the insertion of characters, namely  [  and
       ].   These  commands,  lb  and rb respectively, are required because our use of [ and ] to
       bracket markup commands makes it impossible to directly use [ and ] within the text.

       Our example of their use are the sources of the last sentence in the  previous  paragraph,
       with some highlighting added.

                ...
                These commands, [cmd lb] and [cmd lb] respectively, are required
                because our use of [lb] and [rb] to bracket markup commands makes it
                impossible to directly use [lb] and [rb] within the text.
                ...

   CROSS-REFERENCES
       The  last  two  commands  we  have  to discuss are for the declaration of cross-references
       between documents, explicit and implicit. They are keywords and  see_also.  Both  take  an
       arbitrary number of arguments, all of which have to be plain unmarked text. I.e. it is not
       allowed to use markup on them. Both commands can be used multiple times in a document.  If
       that  is  done  all  arguments  of  all occurrences of one of them are put together into a
       single set.

       keywords
              The arguments of this command are interpreted as keywords describing the  document.
              A  processor  can  use  this  information to create an index indirectly linking the
              containing document to all documents with the same keywords.

       see_also
              The arguments of this command are interpreted as references to other  documents.  A
              processor can format them as direct links to these documents.

       All  the cross-reference commands can occur anywhere in the document between manpage_begin
       and manpage_end. As such the writer can choose whether she  wants  to  have  them  at  the
       beginning  of  the body, or at its end, maybe near the place a keyword is actually defined
       by the main content, or considers them as meta data which should be in the header, etc.

       Our example shows the sources  for  the  cross-references  of  this  document,  with  some
       highlighting added. Incidentally they are found at the end of the body.

                ...
                [see_also doctools_intro]
                [see_also doctools_lang_syntax]
                [see_also doctools_lang_cmdref]
                [keywords markup {semantic markup}]
                [keywords {doctools markup} {doctools language}]
                [keywords {doctools syntax} {doctools commands}]
                [manpage_end]

   EXAMPLES
       Where  ever we can write plain text we can write examples too. For simple examples we have
       the command example which takes a single argument, the text of the argument.  The  example
       text  must  not contain markup. If we wish to have markup within an example we have to use
       the 2-command combination example_begin / example_end instead.

       The first opens an example block, the other closes it, and in between we can  write  plain
       text  and use all the regular text markup commands.  Note that text structure commands are
       not allowed. This also means that it is not possible to embed examples and lists within an
       example.   On the other hand, we can use templating commands within example blocks to read
       their contents from a file (Remember section Advanced structure).

       The source for the very first example in this document (see  section  Fundamentals),  with
       some highlighting added, is

                [example {
                  ... [list_begin enumerated] ...
                }]

       Using example_begin / example_end this would look like

                [example_begin]
                  ... [list_begin enumerated] ...
                [example_end]

   LISTS
       Where  ever  we  can  write  plain  text  we  can  write  lists too. The main commands are
       list_begin to start a list, and list_end to  close  one.  The  opening  command  takes  an
       argument  specifying the type of list started it, and this in turn determines which of the
       eight existing list item commands are allowed within the list to start list items.

       After the opening command only whitespace is allowed, until the first  list  item  command
       opens  the  first  item  of  the  list. Each item is a regular series of paragraphs and is
       closed by either the next list item command, or the end of the list. If closed by  a  list
       item  command this command automatically opens the next list item. A consequence of a list
       item being a series of paragraphs is that all regular text markup can  be  used  within  a
       list item, including examples and other lists.

       The list types recognized by list_begin and their associated list item commands are:

       arguments
              (arg_def)  This opens an argument (declaration) list. It is a specialized form of a
              term definition list where the term is an argument name, with  its  type  and  i/o-
              mode.

       commands
              (cmd_def)  This  opens  a command (declaration) list. It is a specialized form of a
              term definition list where the term is a command name.

       definitions
              (def and call) This opens a general term definition list. The terms defined by  the
              list  items are specified through the argument(s) of the list item commands, either
              general terms, possibly with markup  (def),  or  Tcl  commands  with  their  syntax
              (call).

       enumerated
              (enum) This opens a general enumerated list.

       itemized
              (item) This opens a general itemized list.

       options
              (opt_def)  This  opens  an option (declaration) list. It is a specialized form of a
              term definition list where the term is an option name, possibly with  the  option's
              arguments.

       tkoptions
              (tkoption_def)  This  opens a widget option (declaration) list. It is a specialized
              form of a term definition list where the term is the name of a configuration option
              for a widget, with its name and class in the option database.

       Our  example  is the source of the definition list in the previous paragraph, with most of
       the content in the middle removed.

                ...
                [list_begin definitions]
                [def [const arg]]

                ([cmd arg_def]) This opens an argument (declaration) list. It is a
                specialized form of a definition list where the term is an argument
                name, with its type and i/o-mode.

                [def [const itemized]]

                ([cmd item])
                This opens a general itemized list.

                ...
                [def [const tkoption]]

                ([cmd tkoption_def]) This opens a widget option (declaration) list. It
                is a specialized form of a definition list where the term is the name
                of a configuration option for a widget, with its name and class in the
                option database.

                [list_end]
                ...

       Note that a list cannot begin in one (sub)section and end in  another.  Differently  said,
       (sub)section  breaks  are  not  allowed  within  lists  and list items. An example of this
       illegal construct is

                ...
                [list_begin itemized]
                [item]
                ...
                [section {ILLEGAL WITHIN THE LIST}]
                ...
                [list_end]
                ...

FURTHER READING

       Now that this  document  has  been  digested  the  reader,  assumed  to  be  a  writer  of
       documentation  should  be  fortified  enough  to be able to understand the formal doctools
       language syntax specification as well. From here on  out  the  doctools  language  command
       reference  will also serve as the detailed specification and cheat sheet for all available
       commands and their syntax.

       To be able to validate a document while writing it, it is also recommended to  familiarize
       oneself  with  one  of  the  applications  for  the  processing and conversion of doctools
       documents, i.e. either Tcllib's easy and simple dtplite,  or  Tclapps'  ultra-configurable
       dtp.

BUGS, IDEAS, FEEDBACK

       This  document,  and  the  package  it  describes, will undoubtedly contain bugs and other
       problems.   Please  report  such  in  the  category  doctools  of  the   Tcllib   Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be  made  by going to the Edit form of the ticket immediately after its creation, and then
       using the left-most button in the secondary navigation bar.

SEE ALSO

       doctools_intro, doctools_lang_cmdref, doctools_lang_faq, doctools_lang_syntax

KEYWORDS

       doctools commands, doctools language, doctools markup, doctools syntax,  markup,  semantic
       markup

CATEGORY

       Documentation tools

COPYRIGHT

       Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>