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

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