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