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