mdw@git.distorted.org.uk Git - sgt/halibut/blob - doc/running.but

   1 \C{running} Running Halibut
   2
   3 \I{running Halibut}Running Halibut is very simple. You provide a set
   4 of input files on its \i{command line}, and it produces a set of
   5 output files.
   6
   7 \c $ halibut intro.but getting-started.but reference.but index.but
   8 \e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
   9
  10 This will generate a large set of \i{output files}:
  11
  12 \b \i\c{output.txt} will be a \i{plain text} version of the input
  13 document.
  14
  15 \b \i\c{output.hlp} and \i\c{output.cnt} will be a \i{Windows Help}
  16 version of the same thing. (Most of the text is in \c{output.hlp};
  17 \c{output.cnt} contains additional contents data used by the Windows
  18 help topic selector. If you lose the latter, the former should still
  19 be usable, but it will look less modern.)
  20
  21 \lcont{
  22 Note that Halibut does not require any external software such as a
  23 \i{Help compiler}. It \e{directly} generates Windows Help files, and
  24 therefore it doesn't need to be run on Windows to do so: it can
  25 generate them even when run from an automated script on a Unix
  26 machine.
  27 }
  28
  29 \b \c{output.1} will be a Unix \i{\cw{man} page}.
  30
  31 \b The set of files \c{*.html} will contain an \i{HTML} version of
  32 the document. If you have configured Halibut to generate more than
  33 one HTML file (the default), then the file \c{Contents.html} will be
  34 the topmost one that users should be directed to initially. If you
  35 have configured Halibut to generate a single file, it will be called
  36 \c{Manual.html}.
  37
  38 Unfortunately, in the current version, it is not possible to tell
  39 Halibut to generate these files under different names; so you will
  40 need to \I{renaming files}rename them manually after they are
  41 generated. (Even this won't work for the multiple-file HTML
  42 document, because there will be lots of internal hyperlinks between
  43 the various files which use their names.) Neither is it possible to
  44 tell Halibut not to bother generating some of the output formats, so
  45 you will need to delete any that you don't want.
  46
  47 I regret this inconvenience; it arose because I was more interested
  48 in getting the difficult document-formatting code to work than I was
  49 in sorting out details like this which should be easy. At some point
  50 I plan to add some command-line options to configure all this.