[ntp:questions] Re: Latest changes to TWiki GettingStarted
David L. Mills
mills at udel.edu
Sun Oct 5 19:40:20 UTC 2003
Harlan Stenn wrote:
> In article <3F7F8A8F.4DF90EA2 at udel.edu>, David L. Mills <mills at udel.edu> wrote:
> Please tell me which README files are duplicates of other docs.
The WHERE-TO-START text file is contained in the index.html page.
Actually, I wrote the text file five years ago and neglected to off it.
Mea culpa. The README.versions file should be contained in the
release.html page. The README.refclocks file duplicates information in
the refclock.html page. The READM.hackers and README.patches files are
largely duplicative of the patches.html and porting.html pages. The
README.simulator command line options are in the ntpdsim.html page along
with a comprehensive description not in the text file.
> As for getting rid of text docs in favor of html and a converter, that may
> be OK for some pages but not for anything having to do with building or
> installing the software.
> Perhaps we can auto-generate the texst files, but I will not tolerate using
> a browser when it comes to getting info about how to build/install software.
Yours is an interesting point of view and contrary to the support
philosophy of most computers and parts sellers, which rely on multiple
web pages and download advice. Frankly, I don't care a lot whether text
or browse, but when faced with a choice, I come browse.
> >There are two missing areas that are in some process or other of being
> >addressed lately. One is a touchy-feely O'Reillyian tutorial to explain
> >what ths stuff does, how to build it, how to get it going and how to fix
> >what breaks. I understand a tutorial is already in the works and assume
> >it will be a flat document appropriate to accompany the faq. There is a
> >stunning collection of good NTP tutorials in the Sun Knowledge Base and
> >elsewhere just ripe for links.
> I'm not sure what you mean by the tutorial, and while I have no idea what
> form it may take I suspect that Somebody will find a way to produce a flat
> file if the original is in some other format.
The tutorial written by Dennis Fergusson a dozen years ago and updated
by me in fits and starts and vague ways at haphazard intervals is on the
notes.html page. The quality and relevance of this document are uneven,
and at one time I expected that some volunteer or other would update it.
>From the recent comments on this thread, it appears nobody has read it.
That's completely okay if somebody comes up with a good alternative,
either text or page.
On Mantoads and Webfrogs
The cultural divide between document styles and formats sometimes gets a
bit deep for no good reason. Mantoads cherish monocolor VT100 displays
lit by ASCII text, while webfrogs cherish vericolor monitors lit by
browsers and HTML pages. As I've said many times before, the master
reference pages need to be in one format or the other in order to
provide a definitive reference source. There can of course be multiple
format converters for multiple stylish needs, but the documents produced
are not definitive and may contain errors in translation. I happen to
have chosen HTML because that's the format I believe is most universal
and flexible, although many pages in the collection look very much like
man pages in content.
The fact the current documentation collection contains a great deal of
detail in HTML pages together with a few ASCII text files conceived in
what appears as desperation suggests folks find it hard to update HTML
pages or provide new ones, although several submitted HTML pages are in
the collection now. So, I believe there is a need to make it easier to
maintain HTML documentation pages in the repository. Here is a
suggestion on how this might happen.
First, note that I maintain the master documentation collection using
Adobe GoLive and a web collection on the same machines normally holding
the NTP release and develoment sources. Normally the documentation is
copied from the web collection to the current development version for
the tarball. Suggestion number one is to copy the web collection
directly to the tarball only when the tarball is created, saving an
awkward step. Second, we have to figure out how bitkeeper deals with the
web collection and how that works with GoLive. That shouldn't be hard.
Note that GoLive is clever enough to notice when a page has been changed
other than by GoLive itself, so this makes sure everything is
Suggestion three is that there needs to be a master index in both
formats showing folks the site map and where to go for a quick look at
some particular topic. John Conner suggested this some time ago and I
think it a good idea. A lot of this has already been done in the
preamble of several pages sharing similar content. I fear I'm making
work for me here.
More information about the questions