Osmocom Manuals » History » Version 10
osmith, 07/22/2019 09:53 AM
| 1 | 1 | neels | h1. Osmocom Manuals |
|---|---|---|---|
| 2 | |||
| 3 | 9 | pespin | Osmocom cellular infrastructure projects provide a set of manuals, including: |
| 4 | * User Manuals |
||
| 5 | * VTY Reference Manuals |
||
| 6 | * Protocol / Interface Manuals |
||
| 7 | 1 | neels | |
| 8 | 4 | laforge | The latest versions of the Osmocom GSM Manuals can always be found at |
| 9 | 1 | neels | |
| 10 | https://ftp.osmocom.org/docs/latest/ |
||
| 11 | 8 | osmith | |
| 12 | 9 | pespin | There also is some browsable [[Guidelines for API documentation|API Documentation]] (currently not generated for all libraries). |
| 13 | 1 | neels | |
| 14 | 9 | pespin | h2. Contributing |
| 15 | |||
| 16 | 1 | neels | Contributions are most welcome via [[Gerrit]]. |
| 17 | |||
| 18 | 9 | pespin | If the manual for the program of your particular interest area is missing or you find it incomplete, we kindly ask you for your contribution in form of patches against http://git.osmocom.org/osmo-gsm-manuals/ (or, alternatively [[cellular-infrastructure:Funding]]) |
| 19 | |||
| 20 | h2. Building from source |
||
| 21 | |||
| 22 | Osmocom User Manuals are available in asciidoc format, maintained in the @doc/manuals@ dir of each Osmocom project and can be built with @./configure --enable-manuals@. Shared content is in "osmo-gsm-manuals.git":http://git.osmocom.org/osmo-gsm-manuals/. See "INSTALL.txt":https://git.osmocom.org/osmo-gsm-manuals/tree/INSTALL.txt for further instructions. |
||
| 23 | |||
| 24 | h3. Troubleshooting: Failed to load external entity |
||
| 25 | |||
| 26 | Note that docbook.org since recently are providing DTDs only on HTTPS URLs, while xmllint is incapable of SSL. Hence it is necessary to locally install the docbook DTDs. (On Debian, these are included in the docbook5-xml package.) |
||
| 27 | 10 | osmith | On other distributions (such as Arch Linux), there seems to be no package correctly installing the local docbook DTDs, and building will fail with: |
| 28 | 9 | pespin | <pre> |
| 29 | warning: failed to load external entity "http://docbook.org/xml/5.0/dtd/docbook.dtd" |
||
| 30 | validity error : Could not load the external subset "http://docbook.org/xml/5.0/dtd/docbook.dtd" |
||
| 31 | </pre> |
||
| 32 | |||
| 33 | In order to get stuff build, simply modify @osmo-gsm-manuals.git@'s Makefile include to bypass xmllint call: |
||
| 34 | <pre> |
||
| 35 | diff --git a/build/Makefile.docbook.inc b/build/Makefile.docbook.inc |
||
| 36 | index 373db7d..668796c 100644 |
||
| 37 | --- a/build/Makefile.docbook.inc |
||
| 38 | +++ b/build/Makefile.docbook.inc |
||
| 39 | @@ -33,7 +33,6 @@ all: $(DOCBOOKS_PDF) |
||
| 40 | |||
| 41 | # Create a PDF file and lint it before |
||
| 42 | # xslt path: find includes in both $(OSMO_GSM_MANUALS_DIR)/common/chapters and $(builddir)/generated |
||
| 43 | -%.pdf: %.xml %.xml-lint $(DOCBOOKS_DEPS) build common |
||
| 44 | +%.pdf: %.xml $(DOCBOOKS_DEPS) build common |
||
| 45 | dblatex --xslt-opts="--path $(realpath $(OSMO_GSM_MANUALS_DIR))/common/chapters:$$PWD/generated" \ |
||
| 46 | $(dblatex_quiet) -P draft.mode=no -o $(notdir $@) $< |
||
| 47 | </pre> |
