[ntp:questions] Re: Correcting my time servers clock drift on Alpha ES40s / Tru64

David L. Mills mills at udel.edu
Wed Oct 26 00:39:17 UTC 2005


Tom and the assembled masses,

Too many messages from me, but I have to defend my documentation style 
again. I didn't drop any man pages; I never put them in. There is a tool 
buried in ../scripts that allegedly converts html to man.

As resident carmudgeon, all the documentation I do in support of this 
and other projects is in html and sometimes PDF and sometimes 
PowerPoint. Ordinary people like our faculty and students don't read man 
pages; they read html pages. This is not in any way, shape or form to or 
to not recommend man pages or doc pages or XML pages, but the students, 
most of which are not Unixeers, must have browser-capable pages available.

So, I don't do man pages; I do html pages and now the real gotcha in 
this issue. I am concerned that the icky technical details like an 
equation or two, a diagram or a figure not be lost in translation. So, I 
consider the html documentation to be complete and accurate (even with 
errors or typos) and truly reflect the technical description of the 
animal. Any translation of it to man, doc, Postel ASCII or Hebrew is 
peachy with me, as long as it carries a disclaimer that this is not the 
"official" dcumentation from me and mistrakes can occur in translation.

A hazard to translation is that I frequently update the html 
documentation to reflect a new feature, a more accurate description of 
an old feater or just plain broken English. This means the translations 
can easily diverge from the truth, even if in minor ways. Minor ways 
have a habit of coming back to nip my toenails.

For further consideration, note that I do not update the documentation 
in the distribution; the ISC Corps do that. All I do is update the 
online documentation and the Corps copy what they think is necessary and 
appropriate to the particular distribution. While for the reasons above 
would prefer that man pages not be included in the distribution, I have 
no objection in principle if they are. Heck, many of the program manual 
pages look like man pages in reverse video.

Dave

Tom Smith wrote:

> David Woolley wrote:
> 
>> According to the man pages peer has the following description:
>>
>>
>> Your man pages claim conformance to version 3 of the protocol, and the
>> RFC, but you are clearly running version 4 of the protocol, for which 
>> there
>> is not yet a public specification.  Your supplier has probably simply 
>> retained
>> the man pages from the previous version.  (Personally I strongly disagree
>> with the policy of dropping man pages, but Dave Mills is a rather strong
>> willed person.)
>>
>>
>>> "This command specifies that the local server is to operate in
>>> "symmetric active" mode with the remote server host_address.  In this
>>> mode,the local server can be synchronized to the remote server and, in
>>> addition, the remote server can be synchronized by the local server.
>>> This is useful in a network of servers where, depending on various
>>> failure scenarios, either the local or remote server host may be the
>>> better source of time"
> 
> 
> The latter paragraph is exactly what's in the HTML documentation 
> included in
> that version of ntpd (4.0.98a) by the project. However, I agree that 
> requiring
> every vendor to individualy transcribe the HTML-only documentation into 
> the form
> that users actually want to have it is an invitation to divergence.
> 
> -Tom




More information about the questions mailing list