@c -*- coding: utf-8; mode: texinfo; -*-

@need 1500
@node Website work
@chapter Website work


@node Introduction to website work
@section Introduction to website work

The website is @emph{not} written directly in HTML;
instead it is autogenerated along with the documentation
using Texinfo source files.  Texinfo is the
standard for documentation of GNU software and allows generating
output in HTML, PDF, and Info formats, which drastically reduces
maintenance effort and ensures that the website content is
consistent with the rest of the documentation.  This makes the
environment for improving the website rather different from common
web development.

If you have not contributed to LilyPond before, a good starting
point might be incremental changes to the CSS file, to be found at
@uref{https://lilypond.org/css/lilypond-website.css} or in the
LilyPond source code at @file{./Documentation/css/lilypond-website.css}.

Large scale structural changes tend to require familiarity with
the project in general, a track record in working on LilyPond
documentation as well as a prospect of long-term commitment.

The Texinfo source file for generating HTML are to be found in

@example
Documentation/en/web.texi
Documentation/en/web/*.texi
@end example

Unless otherwise specified, follow the instructions and policies
given in @ref{Documentation work}.  That chapter also contains a
quick introduction to Texinfo; consulting an external Texinfo
manual should be not necessary.

@subheading Exceptions to the documentation policies

@itemize

@item
Sectioning: the website only uses chapters and sections; no
subsections or subsubsections.

@item
@@ref@{@}s to other manuals (@@rnotation, @@rlearning, etc): you can't
link to any pieces of automatically generated documentation, like
the IR or certain NR appendices.

@item
The bibliography in Community->Publications is generated automatically
from @file{.bib} files; formatting is done automatically by
@file{texi-web.bst}.

@item
@dots{}

@item
For anything not listed here, just follow the same style as the
existing website texinfo files.

@end itemize


@node Uploading website
@section Uploading website

@subheading Overall idea

The website is generated by converting the
@file{Documentation/*/web.texi} files to HTML, and reorganizing
the resulting files into @file{out/website-root/}. This is
controlled from toplevel @file{GNUmakefile} and
@file{Documentation/GNUmakefile}.

To build the website, run @code{make website}. This leaves the
website in @file{out/website-root/}.

The website is deployed onto @code{lilypond.org} in the following
steps:

@itemize
@item Run the manual job to build the website, either for the merge
request you want to deploy or for the latest pipeline on @code{master}
at @url{https://gitlab.com/lilypond/lilypond/-/pipelines}, by clicking
the play button.

@item This runs @code{make website} and stores the result in a
@file{website.zip} artifact.

@item On @code{lilypond.org}, the downloader
@url{https://gitlab.com/lilypond/infrastructure/-/blob/master/website/main.go}
is run every 2 hours, from a systemd timed job. If a newer
@file{website.zip} is found, it is unpacked into the
@file{website} directory on @code{lilypond.org}.

@end itemize

@node Debugging website and docs locally
@section Debugging website and docs locally

@itemize
@item
Install Apache (you can use version 2, but keep in mind that the server
hosting lilypond.org runs version 1.3).  These instructions
assume that you also enable @code{mod_userdir}, and use
@code{$HOME/public_html} as DocumentRoot (i.e., the root directory of
the web server).

@item
Build the online docs and website:

@example
make WEB_TARGETS="offline online" doc
make website
@end example

This will make all the language variants of the website.  To save
a little time, just the English version can be made with the
command @code{make WEB_LANGS='' website} or the English and (for
example) the French with @code{make WEB_LANGS='fr' website}.

@item
Choose the web directory where to copy the built stuff.
If you already have other web projects in your DocumentRoot and don't
need to test the @file{.htaccess} file, you can copy to
@code{~/public_html/lilypond.org}.  Otherwise you'd better copy
to @code{~/public_html}.
It's highly recommended to have your build dir and web dir on the
same partition.

@item
Add the directory for the online documentation:

@example
mkdir -p ~/public_html/doc/v2.19/
@end example

You may want to add also the stable documentation in
@code{~/public_html/doc/v2.18/}, extracting the contents of the html
directory present in the tarball available in @rweb{All}. Just in case
you want to test the redirects to the stable documentation.

@item
Copy the files with rsync:

@example
rsync -av --delete out-website/website ~/public_html/
cp out-website/.htaccess ~/public_html
rsync -av --delete out-www/online-root/ ~/public_html/doc/v2.19/
@end example

@end itemize


@node Translating the website
@section Translating the website

As it has much more audience, the website should be translated before
the documentation; see @ref{Translating the documentation}.

In addition to the normal documentation translation practices,
there are a few additional things to note:

@itemize

@item
Build the website with:

@example
make website
@end example

@item
Some of the translation infrastructure is defined in python files;
you must look at the @code{### translation data} sections in:

@example
scripts/build/create-weblinks-itexi.py
scripts/build/website_post.py
@end example

Do not submit a patch to add your language to this file unless
@code{make website} completes with fewer than 5 warnings.

@item
Links to manuals are done with macros like
@code{@@manualDevelLearningSplit}.  To get translated links, you
must change that to @code{@@manualDevelLearningSplit-es} (for
es/Spanish translations, for example).

@end itemize
