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