doc/README.manual

   1 * Overview
   2
   3 This file is a short instruction for maintainers on how to create and
   4 publish the online version of the Tar Manual.
   5
   6 In the sections below we assume that the tar project has been properly
   7 cloned from the git repo, bootstrapped and configured.  We also assume
   8 that top-level directory of the project is the current local directory.
   9
  10 * Creating the web manual
  11
  12 To create the online version of the documentation, run
  13
  14   make -C doc manual-rebuild
  15
  16 This will create the directory doc/manual populated with the tar
  17 documentation files in various formats.  If the doc/manual directory
  18 already exists, it will be removed prior to rebuilding.
  19
  20 The command produces very copious output.  We advise you to examine it
  21 closely to make sure no error messages slip your attention.
  22
  23 For the completeness sake, there are two more Makefile goals related
  24 to the online manual:
  25
  26 ** make -C doc clean-local
  27
  28 Removes the doc/manual directory, if it exists.
  29
  30 ** make -C doc manual
  31
  32 Builds the doc/manual, unless it already exists.
  33
  34 * CVS Repository
  35
  36 The online tar manual[1] is a part of tar web pages[2] and is
  37 traditionally maintained in the CVS repository[3].  To publish the
  38 generated documentation, you will need first to check out tar web
  39 pages from the CVS.  To do so, run
  40
  41   cvs -z3 -d:ext:<username>@cvs.savannah.gnu.org:/web/tar co tar
  42
  43 where <username> is your user name on Savannah.  For the rest of this
  44 document we will assume that the checked out version of the tar web
  45 pages resides in the ~/websrc/tar directory.
  46
  47 If you have already checked out the web pages, be sure to update them
  48 before publishing:
  49
  50   cd ~/websrc/tar
  51   cvs update
  52
  53 * Publishing
  54
  55 To publish the created manual, change to the tar top-level directory
  56 and run:
  57
  58   rsync -avz --exclude CVS --delete manual ~/websrc/tar
  59
  60 This will synchronize the newly created manual pages with the content
  61 of the CVS sandbox.  Then, change to the ~/websrc/tar directory and
  62 schedule any removed files for removal and any new files for addition
  63 to the repository:
  64
  65   cvs diff --brief 2>&1 | sed -n 's/.*cannot find //p' | xargs cvs rm
  66   cvs diff --brief 2>&1 | sed -n 's/^? //p' | xargs cvs add
  67
  68 Then commit your changes:
  69
  70   cvs commit
  71
  72 Once the changes are committed to CVS a job is scheduled on the server,
  73 which synchronizes them with the content of the directory served by
  74 the httpd daemon.  Normally such synchronization happens within
  75 several seconds from the commit.
  76
  77 For more information about CVS, please see its documentation[4].
  78
  79 * References
  80
  81 [1] https://www.gnu.org/software/tar/manual/
  82 [2] https://www.gnu.org/software/tar/
  83 [3] https://web.cvs.savannah.gnu.org/viewvc/tar/
  84 [4] https://www.nongnu.org/cvs/#documentation
  85
  86 \f
  87 Local Variables:
  88 mode: outline
  89 paragraph-separate: "[  \f]*$"
  90 version-control: never
  91 End: