Suggestion for a new doc style

Suggestion for a new doc style

[Richard Hartmann]

Hi all,

I just found out about the new(?) compsys rehash and wondered
when it was introduced so I could replace/amend my own
rehash blurb in my .zshrc.

Thus, I wanted to suggest that all _new_ docs that ware written
have a term like '(introduced in x.y.z)' appended to them.
It would not be much work and build up, over time. If this is
done, I will probably go through the entries lacking that info on
an idle weekend so the old entries get up on par.


Richard

Re: Suggestion for a new doc style

[Bart Schaefer]

On Dec 28, 12:52pm, Richard Hartmann wrote:
} 
} Thus, I wanted to suggest that all _new_ docs that ware written
} have a term like '(introduced in x.y.z)' appended to them.

If this is done (and I'm not at all sure it should be) I think it
should be wrapped up in appropriate yodl conditionals so that it only
appears in the HTML version.  The only value of such an annotation is
when the manual you're reading doesn't match your version of the shell,
which ordinarily can happen only if you're reading the docs online.
Otherwise the doc you have corresponds to the shell you have, and it
would be unnecessary (and to me annoying) to have a continuous history
lesson embedded in the manual.

There's a reason for the ChangeLog file.

Re: Suggestion for a new doc style

[Richard Hartmann]

On Mon, Dec 29, 2008 at 02:46, Bart Schaefer <schaefer@brasslantern.com> wrote:

> If this is done (and I'm not at all sure it should be) I think it
> should be wrapped up in appropriate yodl conditionals so that it only
> appears in the HTML version. The only value of such an annotation is
> when the manual you're reading doesn't match your version of the shell,
> which ordinarily can happen only if you're reading the docs online.
> Otherwise the doc you have corresponds to the shell you have, and it
> would be unnecessary (and to me annoying) to have a continuous history
> lesson embedded in the manual.

I usually edit my RC files on my three main boxes, but I sync them to a
lot of other hosts. In that case, it would be handy to see when something
was introduced directly.


> There's a reason for the ChangeLog file.

True, and it's not hard to use it. Yet, I think the other way would be more
convenient.


Richard