README

   1 CTXT
   2 ====
   3
   4 CTXT is a simple markup processor around html, troff, and latex.
   5
   6 http://litcave.rudi.ir/ (git://repo.or.cz/ctxt.git)
   7
   8 RATIONALE
   9 =========
  10
  11 The markup formats of many typesetting systems like tex and troff,
  12 unlike their outputs, are not ideal and have unpleasant overheads.
  13 But we spend many hours or days using text editors to edit our drafts to
  14 prepare a document.  If the markup itself is not compact and readable,
  15 editing can become frustrating.
  16
  17 On the other hand, markup formats need to support various features
  18 that inevitably make their syntax more complex.  To solve this dilemma,
  19 CTXT provides a simple readable markup text format for common formatting
  20 features, yet does not limit the use of native markup tags.
  21
  22 USAGE
  23 =====
  24
  25 For using ctxt you can invoke:
  26
  27   ctxt -m html <input >output
  28
  29 If -m is omited, troff is assumed.
  30
  31 Supported inline markups include:
  32 * *bold*: bold text
  33 * /italics/: italic text
  34 * |link|: citations in latex or troff and links in html; in html
  35   it can optionally contain a description as |ctxt: http://litcave.rudi.ir/|
  36 * [footnote]: works in troff and latex
  37 * $math$: passed directly to the output; tex or eqn handle it directly
  38 * %raw%: the text is passed unaltered to the output; note that this is not
  39   needed most of the time; use only if it conflicts with ctxt's markup
  40
  41 Supported structural markups include headings, lists, tables and blocks.
  42 The previous paragraph shows a list; it can also start with '-' or '+'
  43 instead of '*'.  When started with a '+', it becomes a definition list
  44 instead of a bullet list.  Indented blocks of text are assumed to be
  45 pre-formatted:
  46
  47   This is a pre-formatted text.
  48
  49 Other kinds of blocks are defined in blocks[] in fmt.c: it contains a
  50 list of string tuples that indicate the pattern of the start and end
  51 of a block.  CTXT ignores the content of these blocks and sends them
  52 directly to the output.  At the moment it includes only troff blocks;
  53 for instance, troff eqn and pic macros are defined as blocks.  But you
  54 can add more entries to blocks[], specially for other backends.
  55
  56 Section headings:
  57   FIRST LEVEL
  58   ===========
  59
  60   SECOND LEVEL
  61   ------------
  62
  63   THIRD LEVEL
  64   ~~~~~~~~~~~
  65
  66 Simple tables:
  67   ============  ==============
  68   Markup        Meaning
  69   ============  ==============
  70   *bold*        bold text
  71   /italic/      italic text
  72   ============  ==============
  73
  74 More complex tables start with .T1 and end with .T2 (like troff macros).
  75 Table format should be specified directly and table entries can be
  76 paragraphs.  Lines starting with "% " are sent to the output unchanged.
  77   .T1
  78   % box expand;
  79   % l l.
  80   + Markup
  81   + Meaning
  82   _
  83   + *bold*
  84   + bold text
  85
  86   + /italic/
  87   + italic
  88     text
  89   .T2
  90
  91 ADVANCED USAGE
  92 ==============
  93
  94 Change backend files, like troff.c or html.c, to tweak tags.
  95 If you use different troff or latex packages, like troff mom:
  96
  97   $ cp troff.c mom.c    # copy a previous backend as a template
  98   $ vi mom.c            # edit it as you wish; rename its fmt_ops struct
  99   $ vi ctxt.c           # add the new fmt_ops to the get_ops()
 100   $ vi Makefile         # add the new object to ctxt dependency list
 101   $ make
 102
 103 Now you can pass the name you chose in get_ops() as the "-m" argument
 104 of ctxt to use your new backend.