[ntp:questions] Re: Latest changes to TWikiGettingStarted

Harlan Stenn stenn at maccarony.ntp.org
Sat Oct 11 02:02:49 UTC 2003


Dave,

I understand your intention but in practice your position makes it
Difficult for a number of people.

In article <3F81BA8F.CB4CB4E at udel.edu>, David L. Mills <mills at udel.edu> wrote:
>I promised to leave you the last word. I lied. Geeze. I get tired of
>being a dartboard and having to repeat my position so many times with so
>little effect.

I understand the feeling.

>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.

I'll try and look again, but the build.html file is the tail of the dog.

The dog is the output of "configure --help".

If there are old files (like WHERE-TO-START, or whatever). I'd like to see
them gone.

>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.

Here's the rub.  Converting the HTML files to other formats may require
tools that people don't have and we should not make them install those tools
just to get documentation in the format they prefer (if it is a format
we "support").

We don't force people to install the auto* generated files, we do it for them.

Ditto for any yacc/lex files.

If we bundle the translated files then we can learn if there is a problem and
fix it, just like any other bug in the system.

If people have to translate their own pages and there is a problem, how do
we reasonably fix it?

How is this class of situation different from the anchor "problems" with
the HTML pages?

>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. Excuse emphasis in the following: WHY NOT
>INCLUDE A TRANSLATION CAPABILITY ON THE WEB? Wouldn't it be clever to
>pipe documentation for the current or an historic version via bitkeeper
>to html2man.pl on the fly? And, while I have discouraged it in the
>interest of archive bloat, I have no objection if the bitkeepers
>maintain a document archive trail paralleling the sources archive trail.

I'm not sure how to implement this.  Where do the source pages come from?

If the *may* come from the user, how do we handle the mechanism of
the translation?  Maccarony is already pretty slow as it is.

Would you use the mechanism you described?  I doubt I would - it's too much
work.

Again, I believe you are trying to impose your local policy choices on
other people.

>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. I do assume
>they have a for-further-information link list somewhere.

Maybe Apple doesn't do it because it is Hard.

>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. Historic documentation for all prior versions is
>available via the repository. I assume everybody knows of this and how
>to use bitkeeper.

You are doing it again.

Many people don't/can't/won't run the latest code.  Telling them "fetch it
from the repo and figure out hyow to build it is just plain wrong and
unfriendly, IMO.

>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.

As I said, trying to enforce ones local policy choices on others leads to
a pissing contest.

H



More information about the questions mailing list