During this season of giving, you can show your support for the NTP Project by making a donation to Network Time Foundation.

GNU AutoGen Improvements

Background and Goals

We want to use GNU AutoGen to produce a variety of .man pages for NTP.

Things we need to be able to do include:

  • Produce pages for sections 1, 4, 5, 8
  • Take the existing ntp-related .man pages from the FreeBSD project and get that information into our .def files, and from these .def files produce our own .man pages (and .texi and .html files)

Implementation Plan

Start with the code on pogo in ntp-gsoc-autogen/, which is a copy of ntpq.8 (for comparison) and a set of AutoGen template files that we should be able to "massage" to the point where we can generate a man page that is a suitable copy of ntpq.8.

Start producing a list of the various .man tags (macros) we will need to implement/translate.

Consider producing a set of .mandoc tags that we will need to implement/translate.

Build a translation table of all of these tags.

Discussion and Comments

Currently Autogen system has capability to produce only man(8) format,but applying little changes we can make its header to read man(1,4 ,5).But the real issue lies whether new macros we need to include should be in same or different file and translation to other format should be done from one format to other or choosing an intermediate format from which translation is quiet easy. Last year in GSOC we tried to concentrate on making a better man page.Rest of issues needed a major changes in AutoGen/AutoOpts code which is written in Sed.We thought it will be better if we replace all these sed script to more flexible perl script.

-- RahulKumar - 23 Mar 2009

As Rahul has mentioned i have same problem. yesterday i sent a draft version of the project proposal to get feedback form harlan and BruceKorb. in that i have mentioned some modules that are already there in the existing AutoGen source. but if we want to support other man page types then we have to modify existing code or provide new source for new features.

-- KapilaBogahapitiya - 26 Mar 2009

this is to make my self clear on the stuff. if we introduce new templates , then most probably we have to change the parser to cater those additions.

-- KapilaBogahapitiya - 26 Mar 2009

Let me clear this two points. Harlan has mentioned that "Take the existing ntp-related .man pages from the FreeBSD project and get that information into our .def files". as i have understood definition file is the thing that user define. what we want to provide is suitable templates to make file definition file.since we are using these is this correct ?.

if we define templates to suite for our purposes would it be a product that all can use. so what if we define considering common scenarios.

Also please tell me where can i find this code on pogo in ntp-gsoc-autogen/.

-- KapilaBogahapitiya - 26 Mar 2009

this is my opint of view regarding how this project should be started . our target is to incoporate abilitiy to produce man pages(several oter types as well) using AutoGen. to achive this we start with implementing man section 1.0.

if we start with man section 1.0 then first thing what are the templates should be incoporated . to do that we have to use NTP's previous man pages. as harlan has mentioned we can use those from FreeBSD project. after desiding templates then main problem becomes will it be suitable for other man pages as well. if not again product will be unsucessfull.

next thing is do we use existing Autogen definition parser or template parser with changes or we include new files for new features. i like to get your feedback on this idea

-- KapilaBogahapitiya - 27 Mar 2009

I think you are on the right path, Kapila.

-- HarlanStenn - 28 Mar 2009

I think the changes needed to add new templates for different man page sections will be very easy.

An easy first step is to look at the test framework I set up with Rahul that will produce .8 pages in addition to .1 pages.

Then, we should find a way to put all the common information used by the .1 and .8 templates into a new file, and include that new file into the (new) .1 and .8 template files.

From there it will be very easy to add new sections.

The actual parser itself probably will not need to be changed. Please take a look at the Makefile in the test framework directory and I think you will see what I mean.

-- HarlanStenn - 28 Mar 2009

Kapila, I missed your earlier questions.

If you look in ntpq/ntpq-opts.def you will see how we have started to add the contents of FreeBSD's man page for ntpq into the .def file.

There are "tags" in that file for formatting; they are probably .mandoc tags but they could be .man tags.

The goal of this project is to find these tags and have AutoGen "do the right thing" with them. If AutoGen is going to produce a .mandoc output file, then no translation is needed. If it is going to produce a .man output file, it will need to do some translation.

We do not have to translate all possible tags to all possible output formats, but we need to translate enough tags.

Our belief is that if we can even get several tags properly translated, it will be much easier to get more tags translated, and eventually we will get them all translated.

Did you find the examples in ntp-gsoc-autogen?

-- HarlanStenn - 28 Mar 2009

where can i find these test framework, where can i find GSOC NTP Autogen source code , it is not listed in previous year project list of google site, could you please help me in this. also i couldn't find examples in ntp-gsoc-autogen

-- KapilaBogahapitiya - 29 Mar 2009

Kapila, ntp-gsoc-autogen is the test framework. If you have some flavor of *ix installed, if you install autogen (and probably automake and autoconf) you will have everything you need to do simple testing.

I will see about creating a CVS repository for this code later today.

You can also find me on #ntp-dev on Libera IRC.

-- HarlanStenn - 29 Mar 2009

OK, I have put the contents of ntp-gsoc-autogen/ up at https://code.google.com/p/ntp-gsoc-autogen/ .

Anybody who wants to look at this code (or hack on it) can visit that link and "go for it". I'm happy to add developers to the project.

-- HarlanStenn - 30 Mar 2009

we provide templates for each type of out put format that user expect(mainly .8 and .1 initially)

and we can write program that read these templates and identify what are the common features and using those common features build new template file. Then user can use that common template file and he has to include if there is some thing that he want to put in to specific page type with the type of that page so that it will not affect or included in other out put files .

please comment on this idea

-- KapilaBogahapitiya - 29 Mar 2009

i am refering to following site to study the man pages that ntp uses


but i can find only 8 type man pages , does ntp support other type of man pages as well

-- KapilaBogahapitiya - 29 Mar 2009

NTP currently has no man pages, everything is in HTML.

The goal of this project is to enhance AutoGen so we can convert the program and configuration files described at GNUAutoGenConversion into separate .def files (see examples in the ntp-gsoc-autogen/ files and in the various ..def files in the NTP source distribution, like ntpq/ntpq-opts.def).

AutoGen currently only produces .1 and.3 pages.

The ntp-gsoc-autogen/ subdirectory is where we were working on producing .1 and .8 pages from the same core AutoGen template. I believe Bruce Korb also sent you an email describing this.

For NTP we want to support .1, .4 (maybe), .5, and .8 pages.

If we choose to support .4 pages we could document the names of the files in /dev that different refclocks want to use.

We will use .5 to document things like ntp.conf and ntp.keys.

Did I forget anything?

-- HarlanStenn - 29 Mar 2009

I Attachment Action Size Date Who Comment
mail.google.com.jpegjpeg mail.google.com.jpeg manage 65 K 03 Apr 2009 - 04:38 KapilaBogahapitiya Harlan, this is the diagram i have sent you
Topic revision: r14 - 23 Jun 2022, DruLavigne
Copyright © by the contributing authors.Use of this website indicates your agreement with, and acceptance of, the PrivacyPolicy, the WikiDisclaimer, and the PrivateWebPolicy.