Where to get ntp man pages ?
Abacom
Where can I can the man pages for ntp?
I got the source and compiled ntpd,
but the documentation seems to be in html format only.
Thanks,
David L. Mills
Good to get this question again, even if asked about once per month.
There has never been, nor will there ever be NTP man pages. There will
always be HTML pages. Modern live, modern culture, modern technology.
Dave
Marc Brett
color HTML with multiple fonts and wrap-around text. Nobody likes this
old fashioned idea of sticking to long established conventions.
> Dave
--
Marc Brett +44 20 8560 3160 WesternGeco
Marc....@WesternGeco.com 455 London Road, Isleworth
ICBM: TQ 15774 76378 (OSGB) Middlesex TW7 5AA UK
Andy Gray
Marc Brett <mbr...@rgs0.london.waii.com> wrote in message news:<a2r9as$2bjm$1...@mail1.wg.waii.com>...
Eric
On 25 Jan 2002 09:42:52 GMT, Marc Brett <mbr...@rgs0.london.waii.com>
wrote for the entire planet to see:
david carlton
> Good to get this question again, even if asked about once per month.
> There has never been, nor will there ever be NTP man pages. There
> will always be HTML pages. Modern live, modern culture, modern
> technology.
I got bitten by this last month; I installed an RPM for ntp on my
Linux system, typed 'man ntp' and 'man ntpd' and so forth and got no
answer. Next on my search path was google. That didn't turn up much
of use; there was an NTP FAQ, but it spent lots of time talking about
'xntpd', which wasn't what I had, and I didn't really feel like
figuring out whether I should download and compile xntpd instead, what
the differences were between xntpd and the ntpd that I had, whether or
not I could trust the information in that file to apply to my version,
etc.
So, in the end, I gave up and guessed (more or less correctly, as it
turned out) as to what the right data to type into ntp.conf was.
Now that I know that this documentation exists, it's not hard to find;
and now I have more steps in my documentation search path in the
future, namely 'rpm -q -d' and '/usr/share/doc'. With luck, that'll
hold me for the next 5 years or so. But probably a decade from now,
I'll install a variant of Unix on a new computer while not having
worried about such issues for the preceding few years, and 'rpm -q -d'
and '/usr/share/doc' won't be the right magic things to type. I bet
that 'man' will still work a decade from now for lots of programs.
So the upshot, from my point of view, is: I appreciate wanting to use
new technology if it works better for you. But from my experience,
there's not a great standard location for documentation other than man
pages. (I see directories for lots of programs in /usr/share/doc, but
the contents of those directories are often scanty.) So how about
putting up a bare-bones man page that basically just says that you're
not willing to maintain a full man page, but that full documentation
does exist elsewhere, and perhaps even some pointers as to where to go
to get it? (E.g. to the version of that documentation at
<http://www.ntp.org/ntp_spool/html/index.htm>; that page is easy to
miss on a quick web search.) Certainly what's distributed now is
adequate for people with either more up-to-date skills than I have or
who are willing to devote more time to installing ntp than I was; but
I doubt I'm the only person who would be helped by a skeleton man page
that wouldn't require much effort to either write or maintain. If I'd
known that the correct information existed somewhere, I wouldn't have
minded digging a bit more to find it.
david carlton | <http://math.stanford.edu/~carlton/>
car...@math.stanford.edu | Go books: <http://math.stanford.edu/~carlton/go/>
Is this my STOP??
David Schwartz
> I got bitten by this last month; I installed an RPM for ntp on my
> Linux system, typed 'man ntp' and 'man ntpd' and so forth and got no
> answer.
Learn to use your tools .;)
rpm -q -l ntp | grep doc
DS
david carlton
Yeah, I know... Here are some possible answers to that:
1) I did learn to use my tools eventually. And, actually, I think
that you should have a -d flag in there instead of grepping for
doc.
2) If I'd known that there were doc files somewhere, I would have done
a bit more poking around (including typing 'man rpm', probably, and
hence learning how to use my tools) and found them. That's why I
think that providing a man page that says nothing more than
'documentation files exist somewhere, but this isn't it' would have
been helpful.
3) I do wish I had time to learn how to use all my tools; I like being
a computer geek. Alas, my job (and my body) won't let me spend as
much time playing around with computers as I'd like. Getting the
ntp running wasn't important enough for me to want to spend more
than a half-hour on it or so.
Who knows, though. I may be overestimating the number of users who
would appreciate a not-very-informative man page; maybe it only works
for people with my peculiar set of out-of-date knowledge and outside
time demands.
david carlton | <http://math.stanford.edu/~carlton/>
car...@math.stanford.edu | Go books: <http://math.stanford.edu/~carlton/go/>
I'm RELIGIOUS!! I love a man with a HAIRPIECE!! Equip me with
MISSILES!!
David Schwartz
> 2) If I'd known that there were doc files somewhere, I would have done
> a bit more poking around (including typing 'man rpm', probably, and
> hence learning how to use my tools) and found them. That's why I
> think that providing a man page that says nothing more than
> 'documentation files exist somewhere, but this isn't it' would have
> been helpful.
I certainly agree that some minimal man pages would be a good idea. At
least enough to say - this is the name of the thing, this is its
purpose, here's the basic syntax (command line options), and here's
where to find out more about it.
> 3) I do wish I had time to learn how to use all my tools; I like being
> a computer geek. Alas, my job (and my body) won't let me spend as
> much time playing around with computers as I'd like. Getting the
> ntp running wasn't important enough for me to want to spend more
> than a half-hour on it or so.
I hope you don't take this the wrong way, but a person really has no
business doing system-administration type tasks on a RedHat machine if
they're not sufficiently familiar with 'rpm' to find out what's included
in a package. That said, there is no reason why things should be more
difficult than they have to be and it's sensible to complain when they
are.
DS
Peter Boettcher
> Good to get this question again, even if asked about once per month.
> There has never been, nor will there ever be NTP man pages. There will
> always be HTML pages. Modern live, modern culture, modern technology.
How about the even more modern solution of XML or SGML? This could be
run through tools to produce HTML, man pages, PDF, chiseled stone
tablets, whatever. Not that I'm volunteering, I kind of like plain
text, myself :)
> Abacom wrote:
>>
>> Sorry...Newbie question I think. Where can I can the man pages for
>> ntp? I got the source and compiled ntpd, but the documentation
>> seems to be in html format only.
--
Peter Boettcher
MIT Lincoln Laboratory
boet...@ll.mit.edu
(781) 981-5275
Christopher Browne
> "David L. Mills" <mi...@udel.edu> writes:
>
> > Good to get this question again, even if asked about once per month.
> > There has never been, nor will there ever be NTP man pages. There will
> > always be HTML pages. Modern live, modern culture, modern technology.
> How about the even more modern solution of XML or SGML? This could
> be run through tools to produce HTML, man pages, PDF, chiseled stone
> tablets, whatever. Not that I'm volunteering, I kind of like plain
> text, myself :)
An interesting option, indeed; DocBook (used with XML/SGML) was
designed to include tagging that allows you to meld together such
things as:
- Q&A, thus allowing building nice looking FAQs;
- Articles, thus allowing the building of stuff like tutorials;
- Tags that map pretty directly to traditional man page structures,
allowing the building of manual pages.
And there are indeed readily available tools on many NTP-capable
platforms to turn this into docs in various forms.
--
(concatenate 'string "cbbrowne" "@acm.org")
http://www.ntlug.org/~cbbrowne/sgml.html
Rules of the Evil Overlord #100. "Finally, to keep my subjects
permanently locked in a mindless trance, I will provide each of them
with free unlimited Internet access. <http://www.eviloverlord.com/>
Jonathan Buzzard
David Schwartz <dav...@webmaster.com> writes:
[SNIP]
>
> I hope you don't take this the wrong way, but a person really has no
> business doing system-administration type tasks on a RedHat machine if
> they're not sufficiently familiar with 'rpm' to find out what's included
> in a package. That said, there is no reason why things should be more
> difficult than they have to be and it's sensible to complain when they
> are.
>
So nobody who knows say Debian or Solaris like the back of their hand
should ever attempt to adminster a RedHat system? I don't agree for
one minute with that statement.
JAB.
--
Jonathan A. Buzzard Email: jona...@buzzard.org.uk
Northumberland, United Kingdom. Tel: +44(0)1661-832195
David Schwartz
> > I hope you don't take this the wrong way, but a person really has no
> > business doing system-administration type tasks on a RedHat machine if
> > they're not sufficiently familiar with 'rpm' to find out what's included
> > in a package. That said, there is no reason why things should be more
> > difficult than they have to be and it's sensible to complain when they
> > are.
> So nobody who knows say Debian or Solaris like the back of their hand
> should ever attempt to adminster a RedHat system?
Huh? I didn't say that. But they should certainly familiarize
themselves with RPM first. Otherwise, they risk doing things the Debian
way or the Solaris way and that just isn't professional.
> I don't agree for
> one minute with that statement.
Fine, then I won't let you do system administration tasks on any of my
machines. If you want to, for example, add a daemon to be started on
system startup to a Solaris machine, you should do it the Solaris way.
You can make it work the FreeBSD way, but it will cause extra headaches
should somebody else need to find and change what you did. You should
know the Solaris way of doing things before you mess with someone's
Solaris machine.
To properly adminsiter a RedHat machine, you *must* understand the
things RedHat does differently from other distributions. One of those
things is the RPM package manager. You simply *must* know how to use it.
It's really that simple. How could you, for example, upgrade Apache or
uninstall mod_ssl, without knowing how to use RPM?
DS
David L. Mills
I don't want to prolong this discussion, since that would not be
productive. However, you should know I prepare the documentation pages
with an ancient text editor using no frames, no java, no fancy fonts
(couple exceptions), no style sheets and absolutely dull and lifeless
typeography. Then I run the pages through tidy so they look presentable
with an ordinary dumb text editor. The result is generally readable,
which is what I intend.
There has been some talk about running the stuff through a magic filter
where html goes in one orifice and man comes out another. I have no
problem with that, but the pages I personally do will be in html.
Dave
Joe Doupnik
> Peter Boettcher <boet...@ll.mit.edu> writes:
>> "David L. Mills" <mi...@udel.edu> writes:
>>
>> > Good to get this question again, even if asked about once per month.
>> > There has never been, nor will there ever be NTP man pages. There will
>> > always be HTML pages. Modern live, modern culture, modern technology.
>
>> How about the even more modern solution of XML or SGML? This could
>> be run through tools to produce HTML, man pages, PDF, chiseled stone
>> tablets, whatever. Not that I'm volunteering, I kind of like plain
>> text, myself :)
>
> An interesting option, indeed; DocBook (used with XML/SGML) was
> designed to include tagging that allows you to meld together such
> things as:
>
> - Q&A, thus allowing building nice looking FAQs;
> - Articles, thus allowing the building of stuff like tutorials;
> - Tags that map pretty directly to traditional man page structures,
> allowing the building of manual pages.
>
> And there are indeed readily available tools on many NTP-capable
> platforms to turn this into docs in various forms.
The name for this is obsfuscation. The goal is to get reading
material in front of eyes right when it is needed most, now. "Tools"
implies a lot of work to realize they are needed, find them, build them,
futz with the source files, find out how to get output where we need it,
and more. DocBook is a very bad offender, by my standards.
If we have something useful to say, just say it plainly. Simple
text works. It's the content; all else is decoration.
I wish NTP had regular man pages. We do need them, and html docs
are not a substitute. Sorry David, html has too many implied requirements.
Multiple forms is just fine, provided the simple one is always present.
Joe D.
Garrett Wollman
> I wish NTP had regular man pages. We do need them, and html docs
>are not a substitute. Sorry David, html has too many implied requirements.
>Multiple forms is just fine, provided the simple one is always present.
FreeBSD ships with manual pages for the NTP suite, although they are
intentionally incomplete and defer to the official documentation as
regards complex or esoteric functions. The person who extracted the
information from the HTML and formatted it in the standard way said
that it was too painful to do again.
-GAWollman
--
Garrett A. Wollman | O Siem / We are all family / O Siem / We're all the same
wol...@lcs.mit.edu | O Siem / The fires of freedom
Opinions not those of| Dance in the burning flame
MIT, LCS, CRS, or NSA| - Susan Aglukark and Chad Irschick
David L. Mills
The file WHERE-TO-START in the top level directory of the NTP
distribution is where to start. It even admits the pages are readable
with a text editor. The comments about xntpd and ntpd are deserved. The
faq should point this out in the introduction and also point out the
differences along the way. However, the typeadillas and minr mistrakes
are forgivable, since we make changes and additions from time to time
and it's pretty hard for the volunteer faq crew to perform brainzone
transfers in real time.
Dave
David Schwartz
> The name for this is obsfuscation. The goal is to get reading
> material in front of eyes right when it is needed most, now. "Tools"
> implies a lot of work to realize they are needed, find them, build them,
> futz with the source files, find out how to get output where we need it,
> and more. DocBook is a very bad offender, by my standards.
In the context of a particular distribution, blame the vendor. The
vendor could/should provide the documentation in whatever format makes
the most sense on that particular platform.
> I wish NTP had regular man pages. We do need them, and html docs
> are not a substitute. Sorry David, html has too many implied requirements.
> Multiple forms is just fine, provided the simple one is always present.
I don't think Dr. Mills is averse to providing man pages provided they
are maintained automagically from the HTML pages. I don't think it's
unreasonable to argue that the default package should include these
without requiring any complex tools be available on the machine
installing the package.
DS
David L. Mills
I did consider modernization, but for the reasons in my last post I
mangle pages with a plain ASCII editor. The reason I do that may not be
obvious. I have rather poor eyesight and that old editor is far more
eye-friendly than the usual authoring tools. That said, the
documentation has evolved over major changes in documentation technology
over the last two decades and with the anticipation of major changes
ahead.
[blast] While my eyesight is worse than most people at my age, the older
among us commonly have nontrivial eyesight degradation. Most of the web
it seems is built by young guys with amazing eyesight that can
interpolate between pixels, especially Microsoft web pages and some of
our own university web pages. I and another faculty member like me have
pursued this issue hotly among the campus webmaster corps, but found
surprisingly unhelpful response. My fervent hope is that I live long
enough to relish their pain as those young eyes grow old and they can't
read the pages either. [tsalb]
Dave
Christopher Browne
> In article <3C51D70B...@webmaster.com>,
> David Schwartz <dav...@webmaster.com> writes:
> [SNIP]
> > I hope you don't take this the wrong way, but a person really has
> > no business doing system-administration type tasks on a RedHat
> > machine if they're not sufficiently familiar with 'rpm' to find
> > out what's included in a package. That said, there is no reason
> > why things should be more difficult than they have to be and it's
> > sensible to complain when they are.
> So nobody who knows say Debian or Solaris like the back of their hand
> should ever attempt to adminster a RedHat system? I don't agree for
> one minute with that statement.
Well, someone who knows RedHat "like the back of their hand" should
probably learn at least a modicum about apt-get and dpkg before trying
to do "surgery" on a Debian system.
Similarly, I'd think it wise to at least know of the _existence_ of
pkginfo, pkgadd, and such before rushing in where angels fear to tread
on a Solaris box.
Knowing that such tools exist isn't exactly rocket science, and
doesn't amount to an expectation that (Har, har!) you need to be up to
the task of building a colloquial Solaris package for XFree86 in order
to be considered competent to administer a Solaris box.
--
(concatenate 'string "cbbrowne" "@ntlug.org")
http://www3.sympatico.ca/cbbrowne/multiplexor.html
Rules of the Evil Overlord #78. "I will not tell my Legions of Terror
"And he must be taken alive!" The command will be: ``And try to take
him alive if it is reasonably practical.''"
<http://www.eviloverlord.com/>
Steve Kostecke
> Peter Boettcher <boet...@ll.mit.edu> writes:
>
>> "David L. Mills" <mi...@udel.edu> writes:
>>
>> > Good to get this question again, even if asked about once per
>> > month. There has never been, nor will there ever be NTP man pages.
>> > There will always be HTML pages. Modern live, modern culture,
>> > modern technology.
>
>> How about the even more modern solution of XML or SGML? This could
>> be run through tools to produce HTML, man pages, PDF, chiseled stone
>> tablets, whatever. Not that I'm volunteering, I kind of like plain
>> text, myself :)
<snip>
> And there are indeed readily available tools on many NTP-capable
> platforms to turn this into docs in various forms.
FWIW I've added links to the HTML program manual pages on
http://www.ntp.org/documentation.html
These links should be visible after the 10PM EST update on 2002/01/25.
--
Steve Kostecke <st...@kostecke.net>
Simon Lyall
> FreeBSD ships with manual pages for the NTP suite, [..]
Debian also has it's own man pages for the ntp programs, these are derived
from the html docs by the look. Of course the the weird thing is that the
.htm files are formatted exactly like a normal manpage with Synopsis,
Description , Files , Bugs and similar parts.
Personally I find manpages very useful, 90% of the time I need them to
lookup some option to the program or find the exact program I need. Having
extensive documentation is great but if I am just trying to remember the
difference between -b and -B in ntpdate the manpage is 10 times quicker
and easier to find.
If David doesn't have the time to create manpages I sure others would be
happy to contribute them.
--
Simon Lyall. | Newsmaster | Work: simon...@ihug.co.nz
Senior Network/System Admin | Postmaster | Home: si...@darkmere.gen.nz
ihug, Auckland, NZ | Asst Doorman | Web: http://www.darkmere.gen.nz
David Woolley
David Schwartz <dav...@webmaster.com> wrote:
> I hope you don't take this the wrong way, but a person really has no
> business doing system-administration type tasks on a RedHat machine if
What you are effectively saying here is that the primary target market
for RedHat systems has no business using them! RedHat is targetted at
the plug and play market that wants something other than Windows, but
isn't prepared to learn how it works. Commercially that probably makes
good sense, even if it does produce newsgroup questions that assume
everyone else in the world is using the same version of the same OS.
David Woolley
David L. Mills <mi...@udel.edu> wrote:
> interpolate between pixels, especially Microsoft web pages and some of
> our own university web pages. I and another faculty member like me have
Remember that, on properly designed pages, you can override the font
size in the browser. The trouble is finding properly designed (relative
font sizes) pages.
> pursued this issue hotly among the campus webmaster corps, but found
> surprisingly unhelpful response. My fervent hope is that I live long
(IANAL).
They are almost certainly in breach of the Americans with Disabilities
Act. I think they may also be covered by "Section 508" of another piece
of legislation which is rather more specific. If they are federally,
or possibly state, funded, they are almost certainly covered by Section
508; a lot of US Univeristies have recently being trying, desperately,
to ensure that they comply with the letter of Section 508, even if not
the spirit.
There is a specific web site on Section 508; it may be:
<http://www.section508.gov/>. You might also be interested
in the World Wide Web Consortium's Web Accessibility Initiative:
<http://www.w3c.org/WAI/> and their public mailing list - see the web
site, I don't want to encourage the less intelligent spammers.
Note that "keeping up with technology" (which in the case of web
pages, means going back to before the invention of HTML!) is normally
the cry of the people who design the most inaccessible pages!
David Woolley
Peter Boettcher <boet...@ll.mit.edu> wrote:
> How about the even more modern solution of XML or SGML? This could be
Dave Mills has written them in SGML! HTML is an instance of SGML.
In the open source community, SGML is often misused to mean DocBook;
is that what you meant? (As HTML is SGML, SGML is considerably less
modern than HTML!)
(I haven't run the pages through nsgmls to find out if they really
are SGML, but if they are not, they are not HTML. Most real life web
pages aren't HTML!)
On the main theme, I certainly vote for man. I find it annoying when
packages have stub man pages that refer one to an info page. I don't
know info enough to navigate it easily and info pages have to be explicitly
included in the master info index (similarly for HTML) whereas
makewhatis will automatically add man pages to the a database for apropos.
I use apropos as my first line of attack when looking for appropriate
commands, etc.
In the case of HTML, there is the added complication that HTML written by
people who dont' understand its philosophy properly (which includes most
"web designers") may not work well on simple browsers and require that
a GUI be run up, or, in some cases, even that an alternative OS be booted.
At the very least, I would like a stub man page, better still would be
a page that documents all the options that a simple user is likely to
want. Even full man pages do refer out to external documentation.
I don't need it myself, now, because I know how to find the documentation
for ntpd, but it is necessary for people who are new to the package, or
know they want time synchronisation but don't know what is already
available on their system.
Jonathan Buzzard
David Schwartz <dav...@webmaster.com> writes:
> Jonathan Buzzard wrote:
>
>> > I hope you don't take this the wrong way, but a person really has no
>> > business doing system-administration type tasks on a RedHat machine if
>> > they're not sufficiently familiar with 'rpm' to find out what's included
>> > in a package. That said, there is no reason why things should be more
>> > difficult than they have to be and it's sensible to complain when they
>> > are.
>
>> So nobody who knows say Debian or Solaris like the back of their hand
>> should ever attempt to adminster a RedHat system?
>
> Huh? I didn't say that. But they should certainly familiarize
> themselves with RPM first. Otherwise, they risk doing things the Debian
> way or the Solaris way and that just isn't professional.
There is a huge different with being familiar with the RedHat way and
knowing almost random options for rpm.
>> I don't agree for
>> one minute with that statement.
>
> Fine, then I won't let you do system administration tasks on any of my
> machines. If you want to, for example, add a daemon to be started on
> system startup to a Solaris machine, you should do it the Solaris way.
> You can make it work the FreeBSD way, but it will cause extra headaches
> should somebody else need to find and change what you did. You should
> know the Solaris way of doing things before you mess with someone's
> Solaris machine.
See above.
> To properly adminsiter a RedHat machine, you *must* understand the
> things RedHat does differently from other distributions. One of those
> things is the RPM package manager. You simply *must* know how to use it.
> It's really that simple. How could you, for example, upgrade Apache or
> uninstall mod_ssl, without knowing how to use RPM?
You can't but you came up with a fairly obscure command line option
to rpm that is certainly not needed in normal package maintainance.
It also requires some file in the ntp package to have doc in it,
which may or may not be the case for some random package.
On a Debian system you need to install ntp-doc otherwise you get nothing,
so for example the equivalent dpkg command line is useless. Though
man ntpd gives a manual page.
Jonathan Buzzard
David Schwartz <dav...@webmaster.com> writes:
[SNIP]
>
> I don't think Dr. Mills is averse to providing man pages provided they
> are maintained automagically from the HTML pages. I don't think it's
> unreasonable to argue that the default package should include these
> without requiring any complex tools be available on the machine
> installing the package.
>
That depends. If the documentation is maintained in format X which
can produce HTML, man, PDF, etc. there is no requirement for tools
to process format X to be need to see the documentation.
What you do is add the building of the HTML and man pages to the
dist target in your makefiles. Then typing 'make dist' builds the
HTML and manpages from the source before packing it up into a tar
ball. You don't even need to distribute format X with ntp if you
don't want.
David Schwartz
> That depends. If the documentation is maintained in format X which
> can produce HTML, man, PDF, etc. there is no requirement for tools
> to process format X to be need to see the documentation.
> What you do is add the building of the HTML and man pages to the
> dist target in your makefiles. Then typing 'make dist' builds the
> HTML and manpages from the source before packing it up into a tar
> ball. You don't even need to distribute format X with ntp if you
> don't want.
This assumes that the machine on which you type 'make dist' has the
tools necessary to convert the manual into the desired format. That or
you have to start including the source code XML-to-HTML and XML-to-man
converters with the NTP distributions, which doesn't make much sense.
DS
David Schwartz
> >> > I hope you don't take this the wrong way, but a person really has no
> >> > business doing system-administration type tasks on a RedHat machine if
> >> > they're not sufficiently familiar with 'rpm' to find out what's included
> >> > in a package. That said, there is no reason why things should be more
> >> > difficult than they have to be and it's sensible to complain when they
> >> > are.
> >> So nobody who knows say Debian or Solaris like the back of their hand
> >> should ever attempt to adminster a RedHat system?
> > Huh? I didn't say that. But they should certainly familiarize
> > themselves with RPM first. Otherwise, they risk doing things the Debian
> > way or the Solaris way and that just isn't professional.
> There is a huge different with being familiar with the RedHat way and
> knowing almost random options for rpm.
Not really. RPM is really the core of the RedHat distribution's way of
managing packages. Querying a package and the most basic query options
(-i and -l) are hardly 'random options'.
> > To properly adminsiter a RedHat machine, you *must* understand the
> > things RedHat does differently from other distributions. One of those
> > things is the RPM package manager. You simply *must* know how to use it.
> > It's really that simple. How could you, for example, upgrade Apache or
> > uninstall mod_ssl, without knowing how to use RPM?
> You can't but you came up with a fairly obscure command line option
> to rpm that is certainly not needed in normal package maintainance.
It really is needed in normal package maintenance. How can you maintain
a package without knowing what's in it. In fact, even far more obscure
RPM options (like --whatprovides) are necessary to maintain a RedHat
system.
> It also requires some file in the ntp package to have doc in it,
> which may or may not be the case for some random package.
I actually would have piped it to more and just looked at the files.
But 'doc' or 'man' are the two most common strings to find in
documentation, so a:
rpm -q -l <package> | egrep "man|doc"
is almost a reflex.
> On a Debian system you need to install ntp-doc otherwise you get nothing,
> so for example the equivalent dpkg command line is useless. Though
> man ntpd gives a manual page.
So if you didn't know that Debian sometimes put the documentation for
'foo' in a corresponding 'foo-doc' package you'd wind up wasting a bunch
of time or worse, finding a sub-optimal solution like installing the
docs yourself from the main NTP distribution.
DS
Nelson Minar
> There has never been, nor will there ever be NTP man pages.
Debian has some - Debian requires a man page for every program
installed. Most of the pages just say "see the HTML", but the ntpd man
page is really quite nice. If someone's writing man pages, it may be a
good place to start.
I won't contribute to the larger "what format should the docs be in?"
debate, but I will say one thing - the NTP source distribution is not
terribly user-friendly. It's a good old school Unix package; read the
docs, configure, select options, install.
For non-experts it's really quite confusing to set up: What's an NTP
server? Where do I find one? What's a stratum? How do I deal with
firewalls? Why do I have to run ntpdate first? Why isn't it working
right away? The various Linux binary distributions (Debian, RedHat)
make it a lot easier; all that's really missing is automatic selection
of NTP servers.
nel...@monkey.org
. . . . . . . . http://www.media.mit.edu/~nelson/
Jonathan Buzzard
To have the tools necessary for processing format X on the machine
you type "make dist" is hardly a major stumbling block, and much
more preferable than everyone needing it. Though I would imagine
that 99% of NTP users never build it from source. I know I have not
that what apt-get is there for.
David L. Mills
It may not be clear that the web pages change all the time. Pages are
added for new drivers, features and options. Pages are repaired and bugs
fixed on old pages and new links added. In fact, the most current pages
appear on the web first and in the software distribution only at the
next version update. This means some new feature described on the web
may not yet be available until the update, and I make no apologies for
that. Tracking these changes in man pages would for me be a nightmare.
If somebody else were to provide man pages based on the web pages, there
will certainly be an update gap.
You will notice occasional links from the web pages to other web sites,
especially for background and support issues. I don't know how Debian
handles these, nor do I have any idea how they derive the synopsis,
etc., which is not in most web pages from here.
You will fiercely dislike my eventual plan, which follows the evolution
of the Windows documentation. Low level help, options and links in the
software distribution, everything else on the web. I know nobody will
like that, but documentation is not a trivial exercise and my job
description has many other required activities.
Dave
Ben Clifford
> So if you didn't know that Debian sometimes put the documentation for
> 'foo' in a corresponding 'foo-doc' package you'd wind up wasting a bunch
> of time or worse, finding a sub-optimal solution like installing the
> docs yourself from the main NTP distribution.
But a person who doesn't know that convention "really has no
business doing system-administration type tasks on a [Debian] machine"
;-)
--
Ben Clifford
http://www.hawaga.org.uk/ben/ GPG: 30F06950
webcam: http://barbarella.hawaga.org.uk/benc-cgi/watchers.cgi
Do not ever send e-mail to: phi...@hawaga.org.uk (seriously!)
Garrett Wollman
>In fact, the most current pages appear on the web first and in the
>software distribution only at the next version update.
Which is a big part of the reason why the Web pages do not meet the
needs of many OS vendors: the documentation has to match the software
we actually provide, not the software the might be available from
David L. Mills & Co. at some unspecified point in the future (or even
the software that is available now, but not from us). This ia pretty
fundamental issue.
David Schwartz
> David Schwartz wrote:
> > So if you didn't know that Debian sometimes put the documentation for
> > 'foo' in a corresponding 'foo-doc' package you'd wind up wasting a bunch
> > of time or worse, finding a sub-optimal solution like installing the
> > docs yourself from the main NTP distribution.
> But a person who doesn't know that convention "really has no
> business doing system-administration type tasks on a [Debian] machine"
> ;-)
That's my point. If you didn't know that, and worked out your own
solution, you could create confusion and problems for someone else.
DS
David L. Mills
Thanks for the links. I've been to some of them, but an still working on
the legal perspective. I have no plans to formally invoke the relevant
statutes, but need to be aware of and understand them and the W3C/WAI
perspective.
Dave
David L. Mills
The intent was to make the pages as simple and readable as possible and
yet remain at least HTML 3.2 compliant, as determined by W3C tidy. Most
are HTML 4.01 compliant. The tidy requires a few things that delight
Explorer but obfusc Netscape, like bullets. I am meek, I am humble, I am
tidy. I don't know where SGML kicks in or out.
Dave
David L. Mills
I was propositioned along with a couple other sturdy folk to write an
O'Reilly book on NTP. My contribution was to be boilerplate, which I
intended to be hard science, while the other two were to develop human
readable prose like you want. It became clear that this prose was not
going to happen anytime soon, so I pulled out leaving my own technical
monograph ready for prime time. Eventually, I hope to find a publisher,
but even if I do, the book will probably be not what you want.
Having said that, the faq is intended as human readable prose and was
built by some pretty savvy guys. The NTP pages, including the briefings,
citations and related documents, are intended primarily as reference
material; however, there really are a few how-tos for a newbie to light
up with absence of forethought. The ASCII WHERE-TO-START text file and
the process begun there is a good place where-to-start. The home page
has a lot of guidance and roadmap, as well as links to the public lists.
The public lists home page has capsule advice how to find servers and
deploy clients, etc. The whole package probably needs more carpentry for
roadmap, but my energy is finite and volunteers are few.
Dave
David L. Mills
You hit the nail absolutely on the head. What you get from me is what
you get from me. The documentation will not match what you require.
Anything else must come from an external source. That is absolutely
fundamental.
Dave
Brian Inglis
>Abacom wrote:
>>
>> Sorry...Newbie question I think.
>> Where can I can the man pages for ntp?
>> I got the source and compiled ntpd,
>> but the documentation seems to be in html format only.
>Good to get this question again, even if asked about once per month.
>There has never been, nor will there ever be NTP man pages. There will
>always be HTML pages. Modern live, modern culture, modern technology.
There's a project/person called GNUmaniak releasing man pages for GNU software
-- perhaps someone knows who it is and could get in touch about converting ntp
docs to man pages.
Should we start a movement to have W3C recognize text/man as a standard mime
type? ;^>
--
Thanks. Take care, Brian Inglis Calgary, Alberta, Canada
Brian....@CSi.com (Brian dot Inglis at SystematicSw dot ab dot ca)
fake address use address above to reply
tos...@aol.com ab...@aol.com ab...@yahoo.com ab...@hotmail.com ab...@msn.com ab...@sprint.com ab...@earthlink.com ab...@cadvision.com ab...@ibsystems.com u...@ftc.gov
spam traps
Brian Inglis
>David L. Mills <mi...@udel.edu> wrote:
>> Abacom wrote:
>>
>>> Sorry...Newbie question I think.
>>> Where can I can the man pages for ntp?
>>> I got the source and compiled ntpd,
>>> but the documentation seems to be in html format only.
>>
>> Good to get this question again, even if asked about once per month.
>> There has never been, nor will there ever be NTP man pages. There will
>> always be HTML pages. Modern live, modern culture, modern technology.
>
>color HTML with multiple fonts and wrap-around text. Nobody likes this
>old fashioned idea of sticking to long established conventions.
And don't forget to top post when you reply! ;^>
[posts reordered in standard sequence]
David Woolley
jona...@buzzard.org.uk (Jonathan Buzzard) wrote:
> To have the tools necessary for processing format X on the machine
> you type "make dist" is hardly a major stumbling block, and much
That wouldn't be consistent with the FSF position on sources distributions
(and, conventionally, "make dist" creates a source distribution) - all
materials have to be distributed in the form in which they are editted,
with the presumption that anyone can then edit them).
> more preferable than everyone needing it. Though I would imagine
> that 99% of NTP users never build it from source. I know I have not
And this is one of the things that will, I think, eventually kill
free software. Free software made sense when there was a fair chance
that users would fix their own bugs and return patches, or provide
upgrades. It doesn't make so much sense when more than 99% of the
users want free software and support but don't give anything back.
Kudos for the writer goes a little way, but many, when they graduate
from college, discover than they need to charge to make a living.
Although it won't make a very large difference, every additional
tool that has to be downloaded raises the barrier to doing ones own
support and contributing back to the project.
For the actual code, of free software, itself, I'm tending to find that
one is stuck with a large number of supplementary downloads before one
can even successfully do make. Up to now, I haven't been able to build
Mozilla because of the time needed to source and build the large number
of pre-requisites. Following a disk failure, I've now updated to a
recent Slackware, so that may have changed.
(If we take this to a little bit more of an extreme, you can create
something that purports to be HTML from Word 2000. A lot of
businesses use MS Word, so why not include the master document in
Word 2000, so that other free software developers have to buy an
Intel machine, a recent Windows and Microsoft Office before they
can contribute to the documentation.)
Jonathan Buzzard
Oh really how on earth is someone supposed to even get to that point
in your book. If you are not allowed to admin a system until you are
an expert how do you become an expert?
I have to say I looked after a RedHat system for 18 months and never
needed to use the random options of rpm that where given in the example.
Sure I was not as efficient as if it was a Debian system or Solaris
system but that is irrelevant. It did not stop me doing the job properly
and the RedHat way either.
David Schwartz
> > That's my point. If you didn't know that, and worked out your own
> > solution, you could create confusion and problems for someone else.
> Oh really how on earth is someone supposed to even get to that point
> in your book. If you are not allowed to admin a system until you are
> an expert how do you become an expert?
How do you learn to fly a plane? Do you just bumble along and make
every mistake? Not with my plane you don't.
My point is not that he shouldn't do this so much as that if he does
this, he should expect to have problems. Remember how we got into this
in the first place, David Carlton argued that because he had difficulty
finding the HTML documentation, man pages should be included in the
distribution. My counter argument was that he wasn't able to find the
documentation because he didn't understand how to use an essential tool
that forms the crux of his distribution. So his problems simply shows
the importance of knowing how to use your tools and doesn't point to any
problem with the NTP distibution.
I'm not saying there isn't one or even that his main point was false,
simply that the problem he experienced cannot be attributed to this
particular cause.
> I have to say I looked after a RedHat system for 18 months and never
> needed to use the random options of rpm that where given in the example.
> Sure I was not as efficient as if it was a Debian system or Solaris
> system but that is irrelevant. It did not stop me doing the job properly
> and the RedHat way either.
You never had to see what files were included in a packages or what
package provided a particular file? I find that extremely hard to
believe unless very little work actually had to be done to the system.
Either that or you drafted elaborate workarounds (like locate | grep ntp
| egrep -i "doc|man"). If you really worked with a RedHat system for 18
months and didn't know those flags, you should find learning them an
incredible relief.
DS
Jonathan Buzzard
David Schwartz <dav...@webmaster.com> writes:
[SNIP]
> You never had to see what files were included in a packages or what
> package provided a particular file? I find that extremely hard to
> believe unless very little work actually had to be done to the system.
> Either that or you drafted elaborate workarounds (like locate | grep ntp
>| egrep -i "doc|man"). If you really worked with a RedHat system for 18
> months and didn't know those flags, you should find learning them an
> incredible relief.
System admin is about doing as little as possible. If you are fiddling
with the system every five minutes you are doing something wrong.
Daily backups, adding new users, applying security updates should
be all you are doing once setup.
Jonathan Buzzard
da...@djwhome.demon.co.uk (David Woolley) writes:
[SNIP]
> And this is one of the things that will, I think, eventually kill
> free software. Free software made sense when there was a fair chance
> that users would fix their own bugs and return patches, or provide
> upgrades. It doesn't make so much sense when more than 99% of the
> users want free software and support but don't give anything back.
> Kudos for the writer goes a little way, but many, when they graduate
> from college, discover than they need to charge to make a living.
It depends, nobody has time to compile up from source all the software
they use. Further nobody has time to be an expert on the internals
of all the software they use. However provided you have some time to
contribute back to one package the system does not break down.
The biggest problem is the increasing amounts of useless bug reports.
"Your program crashed help me" type messages are useless and could
overwhelme the useful ones. It must be almost impossible for Microsoft
to sift through their bug reports.
> Although it won't make a very large difference, every additional
> tool that has to be downloaded raises the barrier to doing ones own
> support and contributing back to the project.
Only if you want to change the documentation.
> For the actual code, of free software, itself, I'm tending to find that
> one is stuck with a large number of supplementary downloads before one
> can even successfully do make. Up to now, I haven't been able to build
> Mozilla because of the time needed to source and build the large number
> of pre-requisites. Following a disk failure, I've now updated to a
> recent Slackware, so that may have changed.
I have not even tried. Some stuff I compile usually stuff I am interested
in contributing to, or stuff I find a bug in I need fixing. Mostly I don't
have time to compile it up.
> (If we take this to a little bit more of an extreme, you can create
> something that purports to be HTML from Word 2000. A lot of
> businesses use MS Word, so why not include the master document in
> Word 2000, so that other free software developers have to buy an
> Intel machine, a recent Windows and Microsoft Office before they
> can contribute to the documentation.)
It is extreme, I would not presume to suggest anything that is not
free to begin with.
Ulrich Windl
> david carlton wrote:
>
> > I got bitten by this last month; I installed an RPM for ntp on my
> > Linux system, typed 'man ntp' and 'man ntpd' and so forth and got no
> > answer.
>
> Learn to use your tools .;)
>
> rpm -q -l ntp | grep doc
However, SuSE names the package xntp still, and the HTML documentation
comes in a separate package, xntpdoc I think. Just to confuse the
Russians. (Did you ever realize that very few of those post here ;-)
>
> DS
Ulrich Windl
> In article <3C51039C...@udel.edu>, "David L. Mills" <mi...@udel.edu> writes:
>
> > Good to get this question again, even if asked about once per month.
> > There has never been, nor will there ever be NTP man pages. There
> > will always be HTML pages. Modern live, modern culture, modern
> > technology.
>
> I got bitten by this last month; I installed an RPM for ntp on my
> Linux system, typed 'man ntp' and 'man ntpd' and so forth and got no
> answer. Next on my search path was google. That didn't turn up much
Maybe someone wites a NTP manual page saying that the documentation is
in HTML.
> of use; there was an NTP FAQ, but it spent lots of time talking about
> 'xntpd', which wasn't what I had, and I didn't really feel like
> figuring out whether I should download and compile xntpd instead, what
> the differences were between xntpd and the ntpd that I had, whether or
> not I could trust the information in that file to apply to my version,
> etc.
The FAQ also says:
4.1.8. What's the difference between xntp and ntp?
Obviously the difference is an x, and it's meaning some years ago was
(according to Professor David L. Mills):
Dennis Fergusson intended the "x" as "experimental". I got maybe twenty
messages over the years suggesting the x was not appropriate for code in
use over a decade and I dropped it for NTPv4. See the paper on NTP history
at http://www.eecis.udel.edu/~mills/papers.htm.
[...]
Ulrich
Ulrich Windl
> In article <m31yge3...@chvatal.cbbrowne.com>, Christopher Browne <cbbr...@acm.org> writes:
[...]
> > An interesting option, indeed; DocBook (used with XML/SGML) was
> > designed to include tagging that allows you to meld together such
> > things as:
> >
> > - Q&A, thus allowing building nice looking FAQs;
> > - Articles, thus allowing the building of stuff like tutorials;
> > - Tags that map pretty directly to traditional man page structures,
> > allowing the building of manual pages.
> >
> > And there are indeed readily available tools on many NTP-capable
> > platforms to turn this into docs in various forms.
> ----------
> The name for this is obsfuscation. The goal is to get reading
> material in front of eyes right when it is needed most, now. "Tools"
> implies a lot of work to realize they are needed, find them, build them,
> futz with the source files, find out how to get output where we need it,
> and more. DocBook is a very bad offender, by my standards.
> If we have something useful to say, just say it plainly. Simple
> text works. It's the content; all else is decoration.
It depends: ASCII has only limited possibilities for emphasis,
footnotes, cross-references, citations, etc. OK, those writing SGML
must be crazy to some degree:
<qandaentry>
<question id="q-meta-update">
<simpara>Where can I get a new version of this document?</simpara>
</question>
<answer>
<para>The following procedure, developed for the &UNIX; operating
system, should provide you with the current version of this document:</para>
<procedure os="UNIX" revision="20000831/UW" userlevel="hacker">
<step>
<simpara>Make sure you have a working version of
<acronym>CVS</acronym> for your operating system, and that you can make
connections to the &IN;.</simpara>
<substeps>
<step>
<simpara>If you are going to update an existing version,
you may directly jump to <xref linkend="faq-step-cvs-update">.</simpara>
</step>
</substeps>
</step>
<!-- more can be found in THE NTP FAQ sources -->
> I wish NTP had regular man pages. We do need them, and html docs
> are not a substitute. Sorry David, html has too many implied requirements.
> Multiple forms is just fine, provided the simple one is always present.
> Joe D.
Ulrich
David L. Mills
Don't laugh. There was a time when NTP was considered critical
technology that could not be revealed beyond COCOM countries.
Dave
David L. Mills
There is such a "NTP manual page". See the WHERE-TO-START file in the
base directory of the software distribution from here. It does say
explicitly that the documentation is in HTML. Should we do something
else or change the file name to make it more obvious?
Dave
Joe Doupnik
What happened to simple expository writing? Man pages do that, and
at the end there are pointers to "read more about it". Very simple. This is
not a help desk with sentence fragment query and responses. It is a
declaration of functionality, and pointers to related documentation. The
urge to change the topic should be resisted. Please don't redirect to other
places right in the middle of things; finish the darned paragraph coherently.
Literary debris goes after the text, as good books have done for eons.
To placate those addited to hypertext, place references in a
separate paragraph following a discussion, as a small section of references
to the just discussed material. Neat, tidy, easy on the eyes and lots
easier to use than stuffing them in the middle of other sentences.
What's wrong here are two basic things. One is diffuse writing,
splattering word-bytes all over the landscape. The other is the issue we
are discussing, which is requiring a substantial pile of goodness knows
what programs to simply get at needed straight talk about the programs.
David was very clear that he perfers writing in one form. Fine.
Rather than push everyone through those hoops, use computers to make the
proper docs as part of the original distribution. Then David's preferences,
and mine, and yours, will be satisfied out of the box, and we will change
from coercing folks to getting along with them.
By way of humorous bad example, I happen to be teaching a course
on Unix device drivers this semester. The book is one from O'Reilly & Assoc.
If you read it then my nic name for it, "the forward reference book," will
be understood. Never finish a topic without saying what you need to know
right here will be discussed later and we won't give you a clue about the
overall concept of things. A podge of last things first, and scattered too.
Ah, the lost art of story telling.
Joe D.
Ted Anderson
few bits of information that might help.
I took one of the URLs from the documentation page[1], for example the
one for ntpd[2], and pasted it into the TOM Server[3] "convert a URL"
box. For "to format" I selected "text". The result, with a tiny bit of
trimming, makes pretty decent contents for /usr/man/cat1/ntpd.1.
Ted Anderson
[1] http://www.eecis.udel.edu/~ntp/documentation.html
[2] http://www.eecis.udel.edu/~ntp/ntp_spool/html/ntpd.htm
[3] http://wheel.compose.cs.cmu.edu:8001/cgi-bin/browse/objweb
Peter Boettcher
> "David L. Mills" <mi...@udel.edu> writes:
>
>> Good to get this question again, even if asked about once per month.
>> There has never been, nor will there ever be NTP man pages. There will
>> always be HTML pages. Modern live, modern culture, modern technology.
>
> How about the even more modern solution of XML or SGML? This could be
> run through tools to produce HTML, man pages, PDF, chiseled stone
> tablets, whatever. Not that I'm volunteering, I kind of like plain
> text, myself :)
After opening my mouth, I decided to do something about it. I have
written a first hack at an NTP HTML2MAN converter. It currently
generates files for all the binaries, as well as for the ntp.conf
file.
It is written in Perl, and unfortunately requires a non-standard perl
module, but I found this extremely easy to download and install.
Pointers are in my source file. Run the file in the html subdirectory
of your NTP tree... output will go into a new 'man' subdirectory
thereof.
http://www.mit.edu/~pwb/ntp/html2man.pl
--
Peter Boettcher
MIT Lincoln Laboratory
boet...@ll.mit.edu
(781) 981-5275
Steve Kostecke
<snip: discussion of various documentation formats>
> There is such a "NTP manual page". See the WHERE-TO-START file in the
> base directory of the software distribution from here. It does say
> explicitly that the documentation is in HTML. Should we do something
> else or change the file name to make it more obvious?
I have added a reference to the "WHERE-TO-START" file in a "newby
notice" which is prominently displayed on almost every page at
www.ntp.org.
As a last resort we could try the <marquee> and <flash> tags or some
annoying Java Applet...
--
Steve Kostecke <st...@kostecke.net>
David L. Mills
Good stuff. Nice to hear from an Englishphile. I'm the terror of the
grad students here about clear English writing, even if some links are
distracting. I expect folks to read the paragraph skipping the
nonforward links, then punch one or another if still curious. I'm also
cherish simple web pages with resizable fonts, frameless and (eek) no
Java. The raw pages are desiged to be almost readable with a dumb text
editor and use no markup appliance whatsoever other than W3C tidy.
As some folks here know, my vision is limited and our University pages
leave much wanting for folks like me. I made a formal complaint citing
certain US statutes and current rulemaking actions. That really cleared
the birds from the attic and the webmaster's guild got a wakeup call
from the vice president. Yummy.
Dave
Joe Doupnik
> Joe,
>
> Good stuff. Nice to hear from an Englishphile. I'm the terror of the
> grad students here about clear English writing, even if some links are
> distracting. I expect folks to read the paragraph skipping the
> nonforward links, then punch one or another if still curious. I'm also
> cherish simple web pages with resizable fonts, frameless and (eek) no
> Java. The raw pages are desiged to be almost readable with a dumb text
> editor and use no markup appliance whatsoever other than W3C tidy.
>
> As some folks here know, my vision is limited and our University pages
> leave much wanting for folks like me. I made a formal complaint citing
> certain US statutes and current rulemaking actions. That really cleared
> the birds from the attic and the webmaster's guild got a wakeup call
> from the vice president. Yummy.
>
> Dave
I guess we can put this thread to rest for another six months.
The gist of it is clear enough from rereading the comments from a variety
of correspondents. It is not to coerce the NTP team into using my favorite
format as their default, but rather to offer a sufficient variety during
program packaging time so that folks can find their "fast path to knowledge
and a bit of humor" without investing days finding and building wierd tools.
That's my view anyway.
Yes, I often end up using vi to cull html for the t part of things.
We should be thankful that the group has not been bitten by the xml bug or
each file would be half a dozen, each nearly useless without its mates and
a battery of analysis programs.
Tiny print. It's the rage these days, sigh. I too need larger type.
Back to more interesting technical discussions.
Joe D.