r21 - 2009-03-28 - 07:01:44 - HarlanStennYou are here: NTP >  Dev Web > GoogleSummerOfCode > GSoC2008doc
NTF needs your help to qualify to participate in the Combined Federal Campaign so we can continue our mission to improve Network Time. We only need a few thousand dollars more by December 31st - any sized donation helps! Please join an NTF Consortium or make a donation to NTF now! THANKS!

Documentation Pre-Processor (Google Summer Of Code - 2008)


Proposal

We are using AutoOpts from GNU AutoGen to handle the command-line options processing of the NTP programs.

AutoOpts has the ability to produce a variety of program documentation, including man pages, html, .texi, and .txt.It consist of set of AutoGen templates and run time library makes it easy to parse command -line option.

Right now, AutoOpts puts "plain text" into its output formats. I'd like to have a framework where we can at least begin to support some sort of "tags" where we can put information into different fonts (like using ntpd when documenting the ntpd command, perhaps "declaring" that we are using a mandoc style and using .Nm whenever we want to see ntpd). I'd also like the ability to document configuration keywords, and perhaps some support for simple tables.

If the "source" for the documentation is used to produce a man page, the output would be a decent-looking man page. If this same source is used to produce .texi page, the resulting .info page should also look good (and perhaps contain appropriate cross-indexes).

We need something more than what we have now, and I would expect that the results of this effort would be incorporated into the AutoGen project, so even more folks could benefit from this work.

One idea I had for this was that one could specify the "format" for the embedded doc strings in the .def file. For example, options could include .man, .mandoc, .texi and .pod (and maybe .html). This "autogen doc processor" would grok the doc strings based on the specified format, and use that info to properly (at least as best as can be done) assist in the production of the various formats.

Here is one possible way to specify this.

 detail = <<- _END_DETAIL 
        Here is a plain-text detail line. 
        _END_DETAIL; 
 
 detail = <<- _END_DETAIL MAN
        .SH This is a section heading.
        _END_DETAIL; 
 
 detail = <<- _END_DETAIL MDOC 
        .Sh This is a section heading.
        _END_DETAIL; 
 
 detail = <<- _END_DETAIL TEXI 
        Here is a @strong{strong} detail line using @code{.texi} markup. 
        _END_DETAIL; 
  
 detail = <<- _END_DETAIL POD 
        =head1 This is a Heading 
        and here is a L<crontab(5)> link to a man page. 
        _END_DETAIL; 

Status Reports and other links

Status Reports: GSoC2008docStatusReports

Sponsoring Organization: http://www.gnu.org/s/soc-projects/ideas.html#autogen

Requirements: C, possibly guile

Related Topics: GNUAutoGenConversion

Preferred License: LGPL

Student: RahulKumar

Mentor: HarlanStenn (with help from BruceKorb, the primary developer of AutoGen)


How do you think his project can be implemented and what exactly the milestone should consist of? I think that I will have to write a plugin or something called "doc processor" in scheme by using guile and incorporate into the autoopts.

-- RahulKumar - 02 May 2008

Rahul,

As for implementation, there is one idea in the proposal above.

I recommend you look at the items in the "Related Topics:" section above and also at the man pages for the various parts of NTP that are included with, for example, FreeBSD.

We figure out a list of items that will need to be formatted for the various output styles we will need. This may include:

  • formatting the program name
  • config file formats/syntax/descriptions
  • info for man page sections (FILES, SEE ALSO, BUGS)

We figure out some ways to do it.

-- HarlanStenn - 02 May 2008

Rahul,

You might want to check out:

http://www.gnu.org/software/autogen/manual/html_node/autogen_325.html#SEC325

and also bug_small.gif Bug #921. There are some other bugs that you might want to at least be aware of - a search for bugs containing the word 'documentation' will find them (and some extras you won't care about).

-- HarlanStenn - 12 Jun 2008

Harlan's suggestion to produce varity of docs seems good. is this idea already implemented since this is exactly after one year

-- KapilaBogahapitiya - 26 Mar 2009

Kapila, we made progress last year and have a much better idea of how to proceed.

This project still needs to be implemented.

-- HarlanStenn - 28 Mar 2009

 

Implementation Milestones

Task Description % Done Delivery Date
Frame work design All the features we want to implement like tag support and support for tables.    
Writing document processor It will be written in LISP/scheme.It will support pre and post triggers.    
Integrating it to AutoGen. By use of GNU AutoMake tools.    
Applying it for NTP. Finally the purpose is met.    
06 Jun Status using mandoc to decide features for man page 100 % 20080606
20 Jun Status making ntpd(8) man page 100 % 20080620
04 Jul Status improving ntpd(8) page   20080704
Midterm Eval Begin Midterm Evaluation   20080707
Midterm Eval Midterm Evaluation Due   20080714
18 Jul Status Biweekly Status Report   20080718
01 Aug Status Biweekly Status Report   20080801
Wrap Up Soft "Pencils Down"   20080811
15 Aug Status Biweekly Status Report   20080815
Project Ends Hard "Pencils Down"   20080818
Final Evaluation Final Evaluation   20080901

-- HarlanStenn - 22 May 2008

 
Edit | WYSIWYG | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r21 < r20 < r19 < r18 < r17 | More topic actions
 
SSL security by CAcert
Get the CAcert Root Certificate
This site is powered by the TWiki collaboration platform
IPv6 Ready
Copyright & 1999-2014 by the contributing authors. All material on this collaboration platform is the property of the contributing authors. Ideas, requests, problems regarding the site? Send feedback