[racket-dev] new `history` form (was: Documentation)

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