[ntp:questions] Re: Latest changes to TWikiGettingStarted

Brad Knowles brad.knowles at skynet.be
Mon Oct 6 20:39:02 UTC 2003


At 6:55 PM +0000 2003/10/06, David L. Mills wrote:

>  1. I said in a previous message to Harlan that I have no objection
>  whatsoever to include compile/build/install text files in the
>  distribution. The distribvution already includes README files for this
>  purpose, although they probably need some tuneup. However, tuned up
>  information is already in the quick.html and build.html HTML pages and
>  can be easily converted to replace or augment the README files.

	You seem to have ignored the fact that I said "we haven't been 
able to provide man pages in the past".  Your clarification dated 
Mon, 06 Oct 2003 03:23:32 +0000 is a very recent development, and the 
previous interpretation of your opinion on this subject is the reason 
why we have been unable to ship man pages for use with the NTP 
Project.  Nevertheless, I did see your clarification, and I made 
reference to that fact.

>  2. Otherwise, my position is that only HTML reference pages be included
>  in the distribution both to reduce bulk and to avoid translation
>  misinterpretation. My concern is mainly about the program and protocol
>  documentation.

	As I see it, this issue seems to be largely resolved.  You're 
concerned mostly about the detailed reference documentation, whereas 
we're concerned about more operational issues.  We just have to 
decide what the best way is to implement the appropriate solution.

>  3. The html2man.pl script in the distribution converts HTML pages to man
>  format. This capability should be mentioned in a prominent place in the
>  distribution and on the web.

	Depending on perl scripts being able to execute correctly in all 
places all over the world is a bad idea.  That is, unless you would 
be willing to also include a full perl interpreter, all the necessary 
libraries, etc....

>                               Excuse emphasis in the following: WHY NOT
>  INCLUDE A TRANSLATION CAPABILITY ON THE WEB?

	Repeat after me:

		The web does not comprise the entire Internet.
		The web does not comprise the entire Internet.
		The web does not comprise the entire Internet.

	Need I write a script that puts the above statement in an infinite loop?

>                                                Wouldn't it be clever to
>  pipe documentation for the current or an historic version via bitkeeper
>  to html2man.pl on the fly?

	Why bother?  Why not just do the conversion once at the remote 
end, and then store that copy?  Anybody who has access to the web 
could just view the versions that are already there.  There would be 
no need for an online translation tool that could take any text fed 
to it, and no need to expose yourself to the risk that they might 
feed you something that could compromise the security of the system.

>  4. If Apple doesn't include NTP documentation in the product, don't
>  blame my policies for that. If they don't like HTML, they can rip off
>  man pages real quick or better yet, link to www.ntp.org.

	The previous understanding of your policies prevented us from 
being able to provide man pages that could be trivially easy for them 
to incorporate into the OS, along with all of the man pages from 
other programs.  They also prevented us from installing our own man 
pages, for those intrepid few who deign to venture out on their own 
and further away from the comfy Apple tree.

	All of Apple's online documentation is in the form of their 
"Help" engine.  Although HTML based, there is no real input to it 
from any external source.  It is pretty much exclusively home-grown 
and home-maintained.

	So, if anyone is going to provide them documentation, it will be 
us -- either because we've provided man pages that Apple can 
trivially incorporate, or we've worked with Apple to convince them 
that they need to ship the officially blessed NTP documentation, or 
we provide NTP documentation compatible with their stuff on our 
website.

>                                                            I do assume
>  they have a for-further-information link list somewhere.

	Nope.

>  5. The NTP documentation on the web is from the latest development
>  version, as the web copy is automatically updated from the master pages
>  each night. Please note with emphasis that these pages are updated
>  frequently as the result of new features, corrections and general
>  cleanup. Therefore, the documentation included in each version applies
>  only to that version.

	Fair enough.  But there is nothing here that would necessarily 
prevent us from providing easier access to the earlier versions of 
the documentation.

>                        Historic documentation for all prior versions is
>  available via the repository.

	Not satisfactory.

>                                I assume everybody knows of this and how
>  to use bitkeeper.

	No more than you do -- at best.  Certainly, there are many people 
in the world who could reasonably expect to run NTP and ntpd but who 
are not developers, and who wouldn't know the first thing about C 
compilers, version control systems, repositories, etc... much less 
anything specific to BitKeeper itself.

>  6. You say "This is a totally unacceptable state of affairs." I find
>  this misleading, unhelpful and inflammatory and would never include
>  anything like that in the Millsspeak lexicon.

	Oh, right.  You just include derogatory terms like "twitchy" for 
things you can't be bothered to learn about.

-- 
Brad Knowles, <brad.knowles at skynet.be>

"They that can give up essential liberty to obtain a little temporary
safety deserve neither liberty nor safety."
     -Benjamin Franklin, Historical Review of Pennsylvania.

GCS/IT d+(-) s:+(++)>: a C++(+++)$ UMBSHI++++$ P+>++ L+ !E-(---) W+++(--) N+
!w--- O- M++ V PS++(+++) PE- Y+(++) PGP>+++ t+(+++) 5++(+++) X++(+++) R+(+++)
tv+(+++) b+(++++) DI+(++++) D+(++) G+(++++) e++>++++ h--- r---(+++)* z(+++)



More information about the questions mailing list