[ntp:hackers] how to update docs, add keywords, add opts, etc.

Harlan Stenn stenn at ntp.org
Sun Aug 4 03:33:38 UTC 2013

Brian Utterback writes:
> I am confused about how to change things in that are autogen-ed and how 
> to get them to autogen.

Autogen changes are driven by changes ot the .def files.

The def files drive:

- the command-line flag parsing code
- the man pages (we produce man and mdoc pages, as we don't know what
  will be installed)
- the generated invoke-*.texi pages

For example, ntpd/ntpd.texi is maintained by hand, and it includes
invoke-ntpd.texi which documents the command-line options.
ntpd/ntpd.html is generated from ntpd/ntpd.texi.

The pages in the html/ are manually maintained, and I get to reconcile
any changes to them with Dave's master copy.

My goal is to replace/supercede the program and file HTML pages
currently in the html/ subdirector with the ones we generate.  That will
not happen until Dave is happy with the quality and content of the pages
we generate.

> I have a repo on pogo. I would like to update the docs and have the 
> chnages propagate to the man pages. It looks to me like the html files 
> in the html directory are the source. IS that correct?

No, sadly.  This was the case when the html pages were of a form that
could be parsed by html2man, but over time the format of the html pages
changed and the html2man script did not keep up.  this is one of the
reasons I wanted to see about producing *all* the program and file docs
form a single set of source in the source tree, with a goal of
satisfying folks who care about man pages (mdoc or man), texi, or html.

> Once I edit a file in the html directory, how do I get it to autogen
> new derivative files?

See https://support.ntp.org/bin/view/Dev/GNUAutoGenConversion and also
note that Oliver Kindernay is a GSoC 2013 student who is working on
doing more cleanup of some of the translators.

If you are OK with mdoc you should be pretty much OK, as the .def files
can take mdoc tags and use them to produce manual pages and texi pages,
the latter will produce html files and our goal is to have these be at
least as good as the ones in the html/ folder.

> Same question for changing the ntp.conf file. It looks like I just need 
> to modify keyword-gen.c and ntp_parser.y, but how do I get it to create 
> new derivative files.

The last time I checked (and did this) was a few months ago - I though
that "make" handled it all for me.  The top of keyword-gen.c says it
will generate ntp_keyword.h and once you're happy with the result you
should commit:


at the samt time.

> Same question (again) for the command line opts.

Those are easier - just edit the .def file and run "make", and when you
are happy check in the changed files.  I use 'bk status -v' to see what
needs to be checked in.

> Finally, is this documented somewhere? I looked in the Wiki and the 
> README files, but didn't find anything.

I don't think there is a README file on this; I don't recall if there is
a wiki topic on it or not.  I seem to be the one who does most all of
this and you're the first person who as asked about it in years.  But
I'm fine working on a wiki topic.

> Oh, and one last thing. Once I get everything up to data, is there a 
> procedure for how to create a distribution tarball from the updated 
> repo? I would like to take the tarball and test it on my target systems.

'gmake distcheck' is what I do.  Most every time I have tried to save
time and only run 'gmake dist' I've had trouble...


More information about the hackers mailing list