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
_______________________________________________
questions mailing list
[email protected]
https://lists.ntp.isc.org/mailman/listinfo/questions
