Cellular Network Infrastructure » Radio Access Network » OsmoBTS

I think it's easiest to have separate reference manuals, one for each of the osmo-bts-* programs. This sticks with our existing tools, processes and the notion that we run one program and generat the vty reference for that program.

regarding osmo-bts exiting: it may be time to finally change that? This was a very early "fail fast" hack in 2011 or so.

laforge wrote:

I think it's easiest to have separate reference manuals, one for each of the osmo-bts-* programs. This sticks with our existing tools, processes and the notion that we run one program and generat the vty reference for that program.

ack

regarding osmo-bts exiting: it may be time to finally change that? This was a very early "fail fast" hack in 2011 or so.

(wrong issue? --> #3011?)

libosmocore now has this patch [1] which allows client programs to dump the XML reference to stdout directly.
At least some osmo-programs support that by the --vty-ref-xml cmdline option: dump the reference and exit

[1] https://git.osmocom.org/libosmocore/commit/?id=cf70aa0c40c574c32b832454f725cc37459c5d8d
"enable vty xml dumping to stdout"

see also
https://git.osmocom.org/osmo-bsc/commit/?id=10983f206ba2d58424bd829c73ebc1ac7e9e7c0b

Generating separate manuals for each BTS model is not addressed yet.

Oh, I didn't know that we have a ticket for this problem. Nice!

Should we change osmo-gsm-manuals to produce N different VTY references, one for each BTS model?

Yep, this sounds like the most reasonable approach. Generating a single file with all model specific options would be better, but more complicated.

I am actually already working on it as a part of SYS#4937. Will submit the patches soon.

After several days of hard work, I am finally getting the first results: *.pdf files are generated separately for all BTS models.

Here are changes for osmo-gsm-manuals:

https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/20950 Makefile.docbook.inc: fix incorrect variable name in documentation
https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/20951 Makefile.vty-reference.inc: create 'generated' in this file
https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/20952 vty_reference_combine.sh: print the final result to stdout

and for osmo-bts-trx:

https://gerrit.osmocom.org/c/osmo-bts/+/20956 doc/manuals: generate XML VTY reference at build-time
https://gerrit.osmocom.org/c/osmo-bts/+/20953 main: do not print asciiart to stdout, remove that printf()
https://gerrit.osmocom.org/c/osmo-bts/+/20954 main: register VTY commands before handle_options()
https://gerrit.osmocom.org/c/osmo-bts/+/20955 osmo-bts-lc15: use consistent name for containing directory

However, the generated *.pdf files still lack documentation for model-specific VTY options. The problem is that those options are registered when 'struct gsm_bts' is allocated (!), and not when the program starts. What's even worse, some commands depend on a global pointer to 'struct gsm_bts'. This needs to be reworked.

I've finally managed to get the model specific options appear in the XML VTY reference:

https://gerrit.osmocom.org/c/osmo-bts/+/20954 main: register VTY commands before handle_options()
https://gerrit.osmocom.org/c/osmo-bts/+/21010 main: move general options from bts_vty_init()
https://gerrit.osmocom.org/c/osmo-bts/+/21011 vty: call bts_model_vty_init() from bts_vty_init()

All changes are submitted for review, once merged - we can close this ticket.

All changes have been merged, new PDFs are available:

http://ftp.osmocom.org/docs/latest/osmobts-lc15-vty-reference.pdf
http://ftp.osmocom.org/docs/latest/osmobts-oc2g-vty-reference.pdf
http://ftp.osmocom.org/docs/latest/osmobts-octphy-vty-reference.pdf
http://ftp.osmocom.org/docs/latest/osmobts-sysmo-vty-reference.pdf
http://ftp.osmocom.org/docs/latest/osmobts-trx-vty-reference.pdf
http://ftp.osmocom.org/docs/latest/osmobts-virtual-vty-reference.pdf