Documentation/contributor/website-work.itexi

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @node Website work
   3 @chapter Website work
   4
   5 @menu
   6 * Introduction to website work::
   7 * Uploading and security::
   8 * Translating the website::
   9 @end menu
  10
  11
  12 @node Introduction to website work
  13 @section Introduction to website work
  14
  15 The website is @emph{not} written directly in HTML;
  16 instead, the source is Texinfo, which is then generated into HTML,
  17 PDF, and Info formats.  The sources are
  18
  19 @verbatim
  20 Documentation/web.texi
  21 Documentation/web/*.texi
  22 @end verbatim
  23
  24 Unless otherwise specified, follow the instructions and policies
  25 given in @ref{Documentation work}.  That chapter also contains a
  26 quick introduction to Texinfo; consulting an external Texinfo
  27 manual should be not necessary.
  28
  29 @subheading Exceptions to the documentation policies
  30
  31 @itemize
  32
  33 @item
  34 Sectioning: the website only uses chapters and sections; no
  35 subsections or subsubsections.
  36
  37 @item
  38 @@ref@{@}s to other manuals (@@ruser, @@rlearning, etc): you can't
  39 link to any pieces of automatically generated documentation, like
  40 the IR or certain NR appendices.
  41
  42 @dots{}
  43
  44 @item
  45 For anything not listed here, just follow the same style as the
  46 existing texinfo files.
  47
  48 @end itemize
  49
  50
  51 @node Uploading and security
  52 @section Uploading and security
  53
  54 FIXME: currently these are plans, not yet completely implemented.
  55 Hey, I'm doing the reponsible "write documentation first, then
  56 code" thing!  I rock!  -gp
  57
  58 The website is generated hourly by user @code{graham} the host
  59 @code{lilypond.org}.  For security reasons, we do not use the
  60 makefiles and scripts directly from git; copies of the relevant
  61 scripts (below) are examined and copied to
  62 @file{~graham/trusted-scripts} on the host.
  63
  64 @example
  65 website.make
  66 scripts/build/extract_texi_filenames.py
  67 @end example
  68
  69 To reduce the CPU burden on the shared host (as well as some
  70 security concerns), the @file{Documentation/pictures/} and
  71 @file{Documentation/web/ly-examples/} directories are @strong{not}
  72 compiled.  If you modify any files in those directories, a user in
  73 the @code{lilypond} group must upload them to @file{~graham/media}
  74 on the host.  This is done by running (locally) @code{make doc},
  75 followed by @code{scripts/build/upload-web-media.sh}.
  76
  77
  78
  79 @node Translating the website
  80 @section Translating the website
  81
  82 As it has much more audience, the website should be translated before
  83 the documentation; see @ref{Translating the documentation}.