X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=sidebyside;f=INSTALL.txt;h=0bd9f80979b774e66471e651ade5fbd6df2f644b;hb=2f1263e2ccdddcac2eb9f7d8ce2ed92867d3d160;hp=594698c1d8e161f3a2f341f5ff30036c45dd70e4;hpb=e90f0536f9be39ada0bef0aeb0d275dec3b2fb5b;p=lilypond.git diff --git a/INSTALL.txt b/INSTALL.txt index 594698c1d8..0bd9f80979 100644 --- a/INSTALL.txt +++ b/INSTALL.txt @@ -27,6 +27,7 @@ INSTALL - compiling and installing GNU LilyPond Generating documentation Documentation editor's edit/compile cycle Building documentation + Building a single document Saving time with `CPU_COUNT' AJAX search Installing documentation @@ -64,8 +65,8 @@ in conjunction with a locally installed copy of the program. For more 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 ============ @@ -377,6 +378,16 @@ run: 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 -------------------------------- @@ -469,7 +480,8 @@ Documentation editor's edit/compile cycle * 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: @@ -478,17 +490,17 @@ Documentation editor's 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 @@ -499,10 +511,17 @@ built by issuing: 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 @@ -512,44 +531,56 @@ _portions_ of the docs. Please do not complain about anything which is 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' ............................