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

GSoC 2008 Documentation Project Status Reports

Related Topics: GSoC2008doc

June 06

Using Mdoc to create manual pages for NTP Project

  • We are using currently man(7) macros for producing manual pages for NTP , which is generated by AutoGen using Autoopts. man(7) page layout leaves the manipulation of fonts and other typesetting details to individual.

  • Autoopts also produce output in plaintext hence there is no scope for font manipulation and page layout.

  • We will be using ManDoc used by freeBsd to produce automated documentation for NTP project to produce more formatted man page.

Advantage of ManDoc over man(7)

  • In -mdoc, page layout macros make up the page structure domain which consists of macros for titles, section headers, displays and lists - essentially items which affect the physical position of text on a formatted page.

  • It has separate manual and general text domain, which makes man page generation easy and consistent.

  • It supports parsing of macros while processing this gives us power to nest micros.

  • We can pass space character in arguments.

Manual page template

The body of a man page is easily constructed from a basic template:

.\" The following commands are required for all man pages.

. Dd Month day, year

.Os [OPERATING_SYSTEM] [version/release]

.Dt DOCUMENT_TITLE [section number] [architecture/volume]

.Sh NAME

.Nm name

.Nd one line description of name

.\" This next command is for sections 2 and 3 only.

.\" .Sh LIBRARY

.Sh SYNOPSIS

.Sh DESCRIPTION

.\" The following commands should be uncommented and

.\" used where appropriate.

.\" .Sh IMPLEMENTATION NOTES

.\" This next command is for sections 2, 3 and 9 function

.\" return values only.

.\" .Sh RETURN VALUES

.\" This next command is for sections 1, 6, 7 and 8 only.

.\" .Sh ENVIRONMENT

.\" .Sh FILES

.\" .Sh EXAMPLES

.\" This next command is for sections 1, 6, 7, 8 and 9 only

.\" (command return values (to shell) and

.\" fprintf/stderr type diagnostics).

.\" .Sh DIAGNOSTICS

.\" .Sh COMPATIBILITY

.\" This next command is for sections 2, 3 and 9 error

.\" and signal handling only.

.\" .Sh ERRORS

.\" .Sh SEE ALSO

.\" .Sh STANDARDS

.\" .Sh HISTORY

.\" .Sh AUTHORS

.\" .Sh BUGS

MANUAL DOMAIN

Addresses

Author Name

Arguments

Configuration Declarations (Section Four Only)

Command Modifiers

Defined Variables

Errno's

Environment Variables

Flags

Function Declarations

Function Types

Functions (Library Routines)

Function Arguments

Return Values

Exit Status

Interactive Commands

Library Names

Literals

Names

Options

Pathnames

Standards

Variable Types

Variables

Manual Page Cross References

GENERAL TEXT DOMAIN

AT&T Macro

BSD Macro

NetBSD Macro

FreeBSD Macro

DragonFly Macro

OpenBSD Macro

BSD/OS Macro

UNIX Macro

Emphasis Macro

Font Mode

Enclosure and Quoting Macros

No-Op or Normal Text Macro

No-Space Macro

Section Cross References

Symbolics

Mathematical Symbols

References and Citations

Trade Names (or Acronyms and Type Names)

Extended Arguments

PAGE STRUCTURE DOMAIN

Section Headers

Subsection Headers

Paragraphs and Line Spacing

Keeps

Examples and Displays

Lists and Columns

*Reference kiss Groff-mdoc sample

Author : Rahul Kumar

 

june 20 (Creating ntpd(8) page)

As reported on on june 6 i was following a approach to create a brand new man page using the manDoc format used by freeBsd.

But it had some shortcomings .

1.We have to add additional support for .cat file which is unnecessary overhead at this time of project.

2.The main goal is to produce a improved man page and converting it to various format and we have pre existing template for creating .1 man page as agman.tpl.

3.So, we came to an idea of producing a new ntpd(8) page by using pre- existing agman.tpl file and writing a new definition file.

Writing a new .def file for ntpd(8)

1.Since we are having pre existing ntpd(8) page from freeBsd ,so i tried to model my ntpd(8) page on that page .

2. First comes the problem that agman1.tpl is only made to produce man(1) pages and since want to produce man(8) page we will have to override "AutoGen5 template man=%s.1".

3.ntpd(8) need to have description , so i added the description in detail = <<- _END_DETAIL section.ntpd(1) had no description.

4.Writing the option section was as easy as to give the definition flag as done in in ntpd(1).

5.I have to add extra sections as how ntp operates and Files which needs some change in template itself.

6. agman1.tpl is only made to create man(1) page ,so to add some extra feature of man(8) pages we need to make it more flexible, along with writing a def file for the man page we want to create.

*Reference kiss URL : https://www.freebsd.org/cgi/man.cgi?query=ntpd&apropos=0&sektion=0&manpath=FreeBSD+7.0-RELEASE&format=ascii

Author : Rahul Kumar

 
Topic revision: r3 - 29 Jun 2008, RahulKumar
Copyright © by the contributing authors.Use of this website indicates your agreement with, and acceptance of, the PrivacyPolicy, the WikiDisclaimer, and the PrivateWebPolicy.