I've added a `history` form to `racket/manual`. The idea is that we
should use `history` within documentation instead of maintaining
"HISTORY.txt" files.
For example, the source of the documentation for `history` is
@defform[(history clause ...) ....]{
Generates a @tech{block} for version-history notes.....
@history[#:added "1.1"]}
As part of the change, I added a `#:packages` clause to
`define-exporting`, so its documentation ends with
@history[#:changed "1.1" @elem{Added @racket[#:packages] clause.}]
If `history` acquires a `#:fish` feature in version "1.2", then its
documentation sources would change to end with something like
@history[#:added "1.1"
#:changed "1.2" @elem{Added @racket[#:fish] option.}]
The `#:added` and `#:changed` modes are currently the only modes.
I imagine that some "HISTORY.txt" files will stick around, but they
will act more like release notes with big-picture summaries, instead of
attempts at change logs (but I'm not sure). Also, I currently plan only
to document changes this way for changes after the v6.0 distribution
(leaving old notes to "HISTORY.txt").
At Sun, 8 Dec 2013 07:37:42 -0700, Matthew Flatt wrote:
> At Sun, 8 Dec 2013 11:09:39 +0100, Jens Axel Søgaard wrote:
> > In cases where the semantics of constructs are changed, should the
> > documentation have a margin note stating the version number of the
> > change?
>
> Yes, it really should.
>
> Details like this get listed in "HISTORY.txt" (the `case` form
> apparently changed in v5.3.2), but no one ever reads "HISTORY.txt", and
> we frequently forget to update it. Putting change information in the
> documentation is clearly better.
>
> Unless someone has an even better idea, I'll add a suitable form to
> `scribble/manual` and start trying to record changes this way.
>
>
> Matthew
>
>
> _________________________
> Racket Developers list:
> http://lists.racket-lang.org/dev
_________________________
Racket Developers list:
http://lists.racket-lang.org/dev
