Generating documentation
Documentation editor's edit/compile cycle
Building documentation
+ Building a single document
Saving time with `CPU_COUNT'
AJAX search
Installing documentation
information, see *note Building documentation without compiling::.
Attempts to compile LilyPond natively on Windows have been
-unsuccessful, though a workaround is available (see *note Lilydev:
-(lilypond-contributor)Lilydev.).
+unsuccessful, though a workaround is available (see *note LilyDev:
+(lilypond-contributor)LilyDev.).
Requirements
============
TODO: Describe what `make' actually does.
+
+
+See also
+........
+
+
+
+ *note Generating documentation:: provides more info on the `make'
+targets used to build the LilyPond documentation.
+
Saving time with the `-j' option
--------------------------------
* Initial documentation build:
make [-jX]
- make [-jX CPU_COUNT=X] doc _## can take an hour or more_
+ make [-jX CPU_COUNT=X] doc _## can take an hour or more_
+ make [-jX CPU_COUNT=X] doc-stage-1 _## to build only PDF documentation_
* Edit/compile cycle:
make [-jX] _## needed if editing outside_
_## Documentation/, but useful anyway_
_## for finding Texinfo errors._
- touch Documentation/*te?? _## bug workaround_
make [-jX CPU_COUNT=X] doc _## usually faster than initial build._
* Reset:
- In some cases, it is possible to clean the compiled documentation
- with `make doc-clean', but this method is not guaranteed to fix
- everything. Instead, we recommend that you delete your `build/'
- directory, and begin compiling from scratch. Since the
- documentation compile takes much longer than the non-documentation
- compile, this does not increase the overall time by a great deal.
+ It is generally possible to remove the compiled documentation from
+ your system with `make doc-clean', but this method is not 100%
+ guaranteed. Instead, if you want to be sure you have a clean
+ system, we recommend that you delete your `build/' directory, and
+ begin compiling from scratch. Since the documentation compile
+ takes much longer than the non-documentation compile, this does
+ not increase the overall time by a great deal.
Building documentation
make doc
- The first time you run `make doc', the process can easily take an
-hour or more. After that, `make doc' only makes changes to the
-pre-built documentation where needed, so it may only take a minute or
-two to test changes if the documentation is already built.
+ or, to build only the PDF documentation and not the HTML,
+
+ make doc-stage-1
+
+ Note: The first time you run `make doc', the process can
+ easily take an hour or more with not much output on the
+ command line.
+
+ After this initial build, `make doc' only makes changes to the
+documentation where needed, so it may only take a minute or two to test
+changes if the documentation is already built.
If `make doc' succeeds, the HTML documentation tree is available in
`out-www/offline-root/', and can be browsed locally. Various portions
broken in those places; the only complete set of documentation is in
`out-www/offline-root/' from the top of the source tree.
+ `make doc' sends the output from most of the compilation to
+logfiles. If the build fails for any reason, it should prompt you with
+the name of a logfile which will provide information to help you work
+out why the build failed. These logfiles are not deleted with
+`make doc-clean'. To remove all the logfiles generated by the
+compilation process, use:
+
+ make log-clean
+
+ `make doc' compiles the documents for all languages. To save some
+compile time, the English language documents can be compiled on their
+own with:
+
+ make LANGS='' doc
+
+Similarly, it is possible to compile a subset of the translated
+documentation by specifying their language codes on the command line.
+For example, the French and German translations are compiled with:
+
+ make LANGS='de fr' doc
+
+Note that this will also compile the English version.
+
Compilation of documentation in Info format with images can be done
separately by issuing:
make info
+An issue when switching branches between master and translation is the
+appearance/disappearance of translated versions of some manuals. If
+you see such a warning from make:
-Known issues and warnings
-.........................
-
-If source files have changed since the last documentation build, output
-files that need to be rebuilt are normally rebuilt, even if you do not
-run `make doc-clean' first. However, build dependencies in the
-documentation are so complex that some newly-edited files may not be
-rebuilt as they should be; a workaround is to `touch' the top source
-file for any manual you've edited. For example, if you make changes to
-a file in `notation/', do:
+ No rule to make target `X', needed by `Y'
- touch Documentation/notation.tely
+Your best bet is to delete the file Y.dep and to try again.
-The top sources possibly affected by this are:
+Building a single document
+..........................
- Documentation/extend.texi
- Documentation/changes.tely
- Documentation/contributor.texi
- Documentation/essay.tely
- Documentation/extending.tely
- Documentation/learning.tely
- Documentation/notation.tely
- Documentation/snippets.tely
- Documentation/usage.tely
- Documentation/web.texi
+It's possible to build a single document. For example, to rebuild only
+`contributor.pdf', do the following:
-You can `touch' all of them at once with:
-
- touch Documentation/*te??
+ cd build/
+ cd Documentation/
+ touch ../../Documentation/contributor.texi
+ make out=www out-www/contributor.pdf
-However, this will rebuild all of the manuals indiscriminately--it is
-more efficient to `touch' only the affected files.
+ If you are only working on a single document, test-building it in
+this way can give substantial time savings - recreating
+`contributor.pdf', for example, takes a matter of seconds.
Saving time with `CPU_COUNT'
............................
projects / lilypond.git / blobdiff