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 The website is generated hourly by user @code{graham} the host
  55 @code{lilypond.org}.  For security reasons, we do not use the
  56 makefiles and scripts directly from git; copies of the relevant
  57 scripts are examined and copied to
  58 @code{~graham/lilypond/trusted-scripts/}
  59
  60 Get latest source code:
  61
  62 @verbatim
  63 ### update-git.sh
  64 #!/bin/sh
  65 cd $HOME/lilypond/lilypond-git
  66 git fetch origin
  67 git merge origin/master
  68 @end verbatim
  69
  70 Check for any updates to trusted scripts / files:
  71
  72 @verbatim
  73 ### check-git.sh
  74 #!/bin/sh
  75 GIT=$HOME/lilypond/lilypond-git
  76 DEST=$HOME/lilypond/trusted-scripts
  77 diff -u $DEST/website.make $GIT/make/website.make
  78 diff -u $DEST/lilypond-texi2html.init $GIT/Documentation/lilypond-texi2html.init
  79 diff -u $DEST/extract_texi_filenames.py $GIT/scripts/build/extract_texi_filenames.py
  80 diff -u $DEST/create-version-itexi.py $GIT/scripts/build/create-version-itexi.py
  81 diff -u $DEST/create-weblinks-itexi.py $GIT/scripts/build/create-weblinks-itexi.py
  82 diff -u $DEST/mass-link.py $GIT/scripts/build/mass-link.py
  83 diff -u $DEST/website_post.py $GIT/scripts/build/website_post.py
  84 diff -u $DEST/lilypond.org.htaccess $GIT/Documentation/web/server/lilypond.org.htaccess
  85 diff -u $DEST/website-dir.htaccess $GIT/Documentation/web/server/website-dir.htaccess
  86 @end verbatim
  87
  88 If the changes look ok, make them trusted:
  89
  90 @verbatim
  91 ### copy-from-git.sh
  92 #!/bin/sh
  93 GIT=$HOME/lilypond/lilypond-git
  94 DEST=$HOME/lilypond/trusted-scripts
  95 cp $GIT/make/website.make $DEST/website.make
  96 cp $GIT/Documentation/lilypond-texi2html.init $DEST/lilypond-texi2html.init
  97 cp $GIT/scripts/build/extract_texi_filenames.py $DEST/extract_texi_filenames.py
  98 cp $GIT/scripts/build/create-version-itexi.py $DEST/create-version-itexi.py
  99 cp $GIT/scripts/build/create-weblinks-itexi.py $DEST/create-weblinks-itexi.py
 100 cp $GIT/scripts/build/mass-link.py $DEST/mass-link.py
 101 cp $GIT/scripts/build/website_post.py $DEST/website_post.py
 102 cp $GIT/Documentation/web/server/lilypond.org.htaccess $DEST/lilypond.org.htaccess
 103 cp $GIT/Documentation/web/server/website-dir.htaccess $DEST/website-dir.htaccess
 104 @end verbatim
 105
 106 Build the website:
 107
 108 @verbatim
 109 ### make-website.sh
 110 #!/bin/sh
 111 DEST=$HOME/web/
 112 mkdir -p $HOME/lilypond/build-website/
 113 cd $HOME/lilypond/build-website/
 114 cp $HOME/lilypond/trusted-scripts/website.make .
 115
 116 make -f website.make WEBSITE_ONLY_BUILD=1 website
 117 rsync -raO $HOME/lilypond/build-website/out-website/website/ $DEST/website/
 118 cp $HOME/src/build-website/out-website/pictures $DEST
 119 cp $HOME/src/build-website/out-website/.htaccess $DEST
 120 @end verbatim
 121
 122 Cronjob to automate the trusted portions:
 123
 124 @verbatim
 125 # website-rebuild.cron
 126 11 * * * * $HOME/lilypond/trusted-scripts/update-git.sh >/dev/null 2>&1
 127 22 * * * * $HOME/lilypond/trusted-scripts/make-website.sh >/dev/null 2>&1
 128 @end verbatim
 129
 130
 131 To reduce the CPU burden on the shared host (as well as some
 132 security concerns), the @file{Documentation/pictures/} and
 133 @file{Documentation/web/ly-examples/} directories are @strong{not}
 134 compiled.  If you modify any files in those directories, a user in
 135 the @code{lilypond} group must upload them to @file{~graham/media}
 136 on the host.
 137
 138 Upload latest pictures/ and ly-examples/ (local script):
 139
 140 @verbatim
 141 ### upload-lily-web-media.sh
 142 #!/bin/sh
 143 BUILD_DIR=$HOME/src/build-lilypond
 144
 145 PICS=$BUILD_DIR/Documentation/pictures/out-www/
 146 EXAMPLES=$BUILD_DIR/Documentation/web/ly-examples/out-www/
 147
 148 cd $BUILD_DIR
 149 rsync -a $PICS graham@lilypond.org:media/pictures
 150 rsync -a $EXAMPLES graham@lilypond.org:ly-examples
 151 @end verbatim
 152
 153
 154 @subsubheading Additional information
 155
 156 Some information about the website is stored in
 157 @file{~graham/lilypond/*.txt}; this information should not be
 158 shared with people without trusted access to the server.
 159
 160 If you have created any files in @file{~graham/lilypond/} then
 161 please run:
 162
 163 @example
 164 chgrp lilypond ~graham/lilypond/ -R
 165 chmod 775 ~graham/lilypond/ -R
 166 @end example
 167
 168 You should symlink your own @file{~/lilypond/} to
 169 @file{~graham/lilypond/}
 170
 171
 172 @node Translating the website
 173 @section Translating the website
 174
 175 As it has much more audience, the website should be translated before
 176 the documentation; see @ref{Translating the documentation}.
 177
 178 In addition to the normal documentation translation practices,
 179 there are a few additional things to note:
 180
 181 @itemize
 182
 183 @item
 184 Build the website with:
 185
 186 @example
 187 make website
 188 @end example
 189
 190 @noindent
 191 however, please note that this command is not designed for being
 192 run multiple times.  If you see unexpected output (mainly the page
 193 footers getting all messed up), then delete your
 194 @file{out-website} directory and run @code{make website} again.
 195
 196 @item
 197 Some of the translation infrastructure is defined in python files;
 198 you must look at the @code{### translation data} sections in:
 199
 200 @example
 201 scripts/build/create-weblinks-itexi.py
 202 scripts/build/website_post.py
 203 @end example
 204
 205 @item
 206 Translations are not included by default in @code{make website}.
 207 To test your translation, edit the @code{WEB_LANGS} line in
 208 @file{make/website.make}.  Do not submit a patch to add your language
 209 to this file unless @code{make website} completes with less than 5
 210 warnings.
 211
 212 @item
 213 Links to manuals are done with macros like
 214 @code{@@manualDevelLearningSplit}.  To get translated links, you
 215 must change that to @code{@@manualDevelLearningSplit-es} (for
 216 es/Spanish translations, for example).
 217
 218 @end itemize
 219
 220
 221