Project

General

Profile

Feature #3036

update vty reference -- and make it so that it can be done without manual edits

Added by neels almost 3 years ago. Updated 3 months ago.

Status:
Resolved
Priority:
High
Assignee:
Category:
-
Target version:
-
Start date:
03/06/2018
Due date:
% Done:

100%

Spec Reference:

Description

osmo-bts has a number of variants: osmo-bts-trx, osmo-bts-sysmo, etc., and each may have some differing VTY commands.
The way we currently generate the vty reference PDF in osmo-gsm-manuals is that we launch the program and issue 'show online-help' on the vty; this outputs an XML of all VTY commands and their docs.
But how do we produce one VTY reference for all of the various BTS types?

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

Decide on the above, generate the VTY reference for each BTS model and update osmo-gsm-manuals.git with it.

Furthermore, osmo-bts-* usually exits right away when there is no BSC to connect to. That's a bit cumbersome when all you want to do is generate the VTY reference XML. Maybe we can introduce a cmdline switch to generate the XML instead of going through the VTY?

History

#1 Updated by laforge almost 3 years ago

  • Assignee set to neels

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.

#2 Updated by neels almost 3 years ago

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?)

#3 Updated by neels 3 months ago

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.

#4 Updated by fixeria 3 months ago

  • Status changed from New to In Progress
  • Assignee changed from neels to fixeria
  • Priority changed from Normal to High

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.

#5 Updated by fixeria 3 months ago

  • % Done changed from 0 to 80

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.

#6 Updated by fixeria 3 months ago

  • Status changed from In Progress to Feedback
  • % Done changed from 80 to 100

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.

Also available in: Atom PDF

Add picture from clipboard (Maximum size: 48.8 MB)