Generating loadparm from our XML documentation
ab at samba.org
Thu Jan 9 15:31:24 MST 2014
On Thu, Jan 09, 2014 at 12:49:42PM -0500, David Collier-Brown wrote:
> On 01/09/2014 12:20 PM, Michael Adam wrote:
> > We certainly discussed this more than once, and I definitely
> > said I would love to introduce once central place to store
> > all information about a parameter, and generate all and doc
> > from that. I would even be surprised if anyone would
> > question this.
> > But I definitely never suggested to generate code from the xml
> > docs. Instead, what I suggested at the time is to have one
> > central python program to generate all code and the xml doc
> > sources for the parameters from python data structures.
> My experience with Donald Knuth's /tangle/ and /weave/ programs suggest
> this is a good idea for anything where the description is substantially
> larger than the code. If you can find a copy of the TeXBook, look at
> the first quarter or so. Conversely, if the code is much larger than the
> document, tangle/weave is overkill: see the last quarter of the TeXBook
> for that.
> I've not done this with XML, but it took about a man-day to recreate
> tangle, so it shouldn't take more than a week fiddling with XML parsers
Majority of param functions is small, certainly less than 10 lines of
code each. Most of string parameters are actually one-liners, hidden
behind a macro (per parameter scope and type). The rest are defaults and
synonyms handling -- these will make a bit of work to pull down from XML
due to the fact that they need to be verified but that applies to any
refactoring around parameters directed to either way -- even if we would
want to check whether our documentation is correct.
/ Alexander Bokovoy
More information about the samba-technical