README

   1 CTXT
   2 ====
   3
   4 CTXT is a simple markup processor around html, latex and troff.
   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 roff, unlike
  12 their output, are not ideal and have unpleasant overheads.  But we
  13 spend many hours or days with our text editors and edit our drafts to
  14 prepare a document.  If the markup itself is not compact and readable,
  15 editing would be a lot harder.
  16
  17 On the other hand, markup formats need to support various features that
  18 inevitably make their syntax more complex.  CTXT provides a simple
  19 readable markup text format for common formatting features, yet does
  20 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*
  33 * /italics/
  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 '*'.  Indented blocks of text are assumed to be preformatted:
  44
  45   This is a preformatted text.
  46
  47 Other kinds of blocks are defined in blocks[] in fmt.c: it contains a
  48 list of string tuples that indicate the pattern of the start and end
  49 of a block.  CTXT ignores the content of these blocks and sends them
  50 directly to the output.  For instance, troff eqn and pic macros are
  51 defined as blocks.  You can add more entries to blocks[].
  52
  53 Section headings:
  54   FIRST LEVEL
  55   ===========
  56
  57   SECOND LEVEL
  58   ------------
  59
  60   THIRD LEVEL
  61   ~~~~~~~~~~~
  62
  63 Simple tables:
  64   ============  ==============
  65   Markup        Meaning
  66   ============  ==============
  67   *bold*        bold text
  68   /italic/      italic text
  69   ============  ==============
  70
  71 More complex tables start with .T1 and end with .T2 (like troff macros).
  72 Table format should be specified directly and table entries can be
  73 paragraphs.
  74   .T1
  75   box expand;
  76   l l.
  77   =
  78   * Markup
  79   * Meaning
  80   =
  81   * *bold*
  82   * bold text
  83   _
  84   * /italic/
  85   * italic
  86     text
  87   =
  88   .T2
  89
  90 ADVANCED USAGE
  91 ==============
  92
  93 Change backend files, like troff.c or html.c, to tweak tags.
  94 If you use different troff or latex packages, like troff mom:
  95
  96   $ cp troff.c mom.c    # copy a previous backend as a template
  97   $ vi mom.c            # edit it as you wish; rename its fmt_ops struct
  98   $ vi ctxt.c           # add the new fmt_ops to the get_ops()
  99   $ vi Makefile         # add the new object to ctxt dependency list
 100   $ make
 101
 102 Now you can pass the name you chose in get_ops() as the "-m" argument
 103 of ctxt to use your new backend.