Date: Sun, 1 Feb 2004 15:03:12 +0100 From: "Simon L. Nielsen" <simon@FreeBSD.org> To: Tom Rhodes <trhodes@FreeBSD.org> Cc: FreeBSD-doc@FreeBSD.org Subject: Re: RFC: Automated process for documenting tunables/variables. Message-ID: <20040201140310.GC748@arthur.nitro.dk> In-Reply-To: <20040126223652.49bb27a7@localhost> References: <20040122024729.2944fada@localhost> <20040124232359.GJ41072@arthur.nitro.dk> <20040126223652.49bb27a7@localhost>
index | next in thread | previous in thread | raw e-mail
[-- Attachment #1 --]
[I just merged the two mails]
On 2004.01.26 22:36:52 -0500, Tom Rhodes wrote:
> On Sun, 25 Jan 2004 00:24:00 +0100
> "Simon L. Nielsen" <simon@FreeBSD.org> wrote:
>
> > On 2004.01.22 02:47:29 -0500, Tom Rhodes wrote:
> > > About three weeks ago Marc Silver kicked me in the butt to start
> > > working on this project again. First off, I did not drop the front
> > > page; only working on that and other projects at the same time.
> >
> > Good, I really miss my link to the events page... :-).
>
> I want to put that into a 'community' section, but this email isn't
> about this.
Indeed, I just wanted to do a slight poke :-).
> > > I'm not sure how it could be integrated with or why it should be
> > > integrated with a buildworld.
> >
> > If it should be integreated with buildworld it should be made much
> > faster. The speed isn't a problem when just running the script once in
> > a while, but if all buildworlds had to wait for it, I think people would
> > complain.
> >
> > It could be nice to integrate with buildworld to avoid having the
> > generated manual page in CVS, but I don't think it's that important.
>
> I could be/would be, but require code changes which I don't like.
> Addition of macros and perhaps more functions in sysctl.h.
>
> Not sure if that method is a good idea. There should be no
> problem with me doing the general updating every now and again.
No, I think it's the best solution, at least I can't come up with a
better one.
> > - A lot of the mdoc lines in run.sh are broken up (which of course isn't
> > an error, but since it's a new file it might as well be done right).
> >
> > E.g. :
> >
> > "While some sysctls may be used
> > to alter the system behavior on-the-fly,"
>
> Would rather not make them longer than 72 characters but I can
> see what you mean. It might look a bit nicer to have them
> in more sentence length.
Indeed the shouldn't be longer than 72, but as short as they were in
your patch seemed a bit short.
> > - For undocumented variables, it looks odd with the '()' below. I have
> > attached a patch which only prints '.Pq Vt ${type}' if there actually is
> > a type.
>
> Thanks for the patch, i'll give it a whirl. I like this a little
> better than our previous incantation.
Great :).
> > - In the generated manual page "This manual page automatically generated
> > once a month by a script..." - I think that makes it sound like it's
> > updated once a month on the end users systems. I don't have a good
> > suggestion for another wording right now though...
>
> Perhaps something similar to:
>
> This manual page is generated for every release.
>
> But i'm sure that something else will be more realistic.
That sounds better to me.
If you have an updated patch just, feel free to throw a version my way.
--
Simon L. Nielsen
FreeBSD Documentation Team
[-- Attachment #2 --]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (FreeBSD)
iD8DBQFAHQceh9pcDSc1mlERAjC0AJ4ghSpcouRxmlgwFN40iEDtmBcvxwCgwq6r
DuvArVmcPMCLmz+jNud/7m0=
=xf3q
-----END PGP SIGNATURE-----
help
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20040201140310.GC748>