History changes

[Sorawee Porncharoenwase]

Hi Racketeers,

Laurent Orseau asked if it’s possible for the release announcement to include @history changes (compared to the previous release), because some small but useful changes might go unnoticed otherwise. I think this is a great idea, so I tried to implement the feature. The result for 8.0 release is included at the end of the email. However, I’m not satisfied with my current approach, and I would appreciate it if anyone could suggest a way to improve it.

My current workflow is:

1. Download two Racket versions that I want to diff @history.
2. Patch share/pkgs/scribble-lib on both versions
3. Run raco setup -c scribblings; HISTORY_INFO_PATH=/path/to/info raco setup scribblings on both versions
4. Run the diffing program on the two info files.

Patching scribble-lib is something I want to avoid. Specifically, I need to modify scribble-lib to

• modify history to recognize HISTORY_INFO_PATH and emit information. This alone is enough to get all information except the “who I am” field (see below)
• modify all documenting forms, like defform, defproc, etc. so that it cooperates with history to supply “who I am” field. This is further complicated by the fact that deftogether exists, so I need to hack the with-togetherable-racket-variables protocol to keep the information around.

It would be nice if I don’t have to modify scribble-lib, or, failing that, avoid touching documenting forms. Isn’t it possible for history to know which defform it’s under?

Anyhow, here's the output for v8.0

who: #%declare
package: base
source: racket-doc/scribblings/reference/syntax.scrbl:433:19
desc:
  Changed in version 7.9.0.5: Added #:unsafe.


who: system-type
package: base
source: racket-doc/scribblings/reference/runtime.scrbl:132:19
desc:
  Changed in version 7.9.0.6: Added 'os* and 'arch modes.


who: _cprocedure
package: base
source: racket-doc/scribblings/foreign/types.scrbl:780:19
desc:
  Changed in version 7.9.0.16: Added the #:varargs-after argument.


who: _fun
package: base
source: racket-doc/scribblings/foreign/types.scrbl:916:19
desc:
  Changed in version 7.9.0.16: Added the #:varargs-after option.


source: racket-doc/scribblings/raco/setup.scrbl:383:19
desc:
  Changed in version 7.9.0.3: Added PLT_SETUP_NO_FORCE_GC, PLT_SETUP_SHOW_TIMESTAMPS, and --sync-docs-only.


source: racket-doc/scribblings/raco/decompile.scrbl:37:19
desc:
  Changed in version 1.9: Added --partial-fasl.


package: compiler-lib
source: racket-doc/scribblings/raco/test.scrbl:198:19
desc:
  Changed in version 1.8: Added --output and -o.


package: base
source: racket-doc/scribblings/reference/syntax-model.scrbl:450:19
desc:
  Changed in version 7.9.0.13: Added implicit-made-explicit properties.


who: fx+/wraparound
package: base
source: racket-doc/scribblings/reference/fixnums.scrbl:104:17
desc:
  Added in version 7.9.0.6.


who: bytes-open-converter
package: base
source: racket-doc/scribblings/reference/bytes.scrbl:520:19
desc:
  Changed in version 7.9.0.17: Added built-in converters for "WTF-8", <"WTF-8-permissive", and "WTF-16".


who: hash-intersect
package: base
source: racket-doc/scribblings/reference/hashes.scrbl:795:17
desc:
  Added in version 7.8.0.11.


package: base
source: racket-doc/scribblings/reference/cont.scrbl:105:19
desc:
  Changed in version 7.9.0.13: The name argument gives the name of the prompt tag.


who: object-name
package: base
source: racket-doc/scribblings/reference/struct-inspectors.scrbl:191:20
desc:
  Changed in version 7.9.0.13: Recognize the name of continuation prompt tags.


who: unsafe-fx+/wraparound
package: base
source: racket-doc/scribblings/reference/unsafe.scrbl:91:17
desc:
  Added in version 7.9.0.6.


who: unsafe-set-immutable-car!
package: base
source: racket-doc/scribblings/reference/unsafe.scrbl:306:17
desc:
  Added in version 7.9.0.18.


who: editor:silent-cancel-on-save-file-out-of-date?
package: gui-lib
source: gui-lib/framework/main.rkt:1634:18
desc:
  Added in version 1.53.


who: make
package: gui-lib
source: gui-doc/scribblings/gui/tab-panel-class.scrbl:65:19
desc:
  Changed in version 1.55: Added the 'can-reorder and 'can-close styles.


who: on-reorder
package: gui-lib
source: gui-doc/scribblings/gui/tab-panel-class.scrbl:121:17
desc:
  Added in version 1.55.


who: on-close-request
package: gui-lib
source: gui-doc/scribblings/gui/tab-panel-class.scrbl:132:17
desc:
  Added in version 1.55.


who: on-superwindow-activate
package: gui-lib
source: gui-doc/scribblings/gui/window-intf.scrbl:481:19
desc:
  Added in version 1.54.


who: message-box/custom
package: gui-lib
source: gui-doc/scribblings/gui/dialog-funcs.scrbl:355:19
desc:
  Changed in version 1.53: Added the return-the-dialog? argument and the ability to change the dialog box's message.


who: message+check-box
package: gui-lib
source: gui-doc/scribblings/gui/dialog-funcs.scrbl:388:19
desc:
  Changed in version 1.53: Added the return-the-dialog? argument and the ability to change the dialog box's message and check label.


who: current-text-keymap-initializer
package: gui-lib
source: gui-doc/scribblings/gui/editor-funcs.scrbl:144:19
desc:
  Changed in version 1.51: Changed Unix keybindings in the default initializer to match Windows, dropping start-of-line and end-of-line bindings.


who: make-unix-socket-tcp@
package: unix-socket-lib
source: unix-socket-doc/scribblings/socket/unix-socket.scrbl:138:17
desc:
  Added in version 1.3.


who: close-ith-tab
package: drracket
source: drracket/scribblings/tools/unit.scrbl:669:19
desc:
  Added in version 1.9.


who: close-given-tab
package: drracket
source: drracket/scribblings/tools/unit.scrbl:675:19
desc:
  Added in version 1.9.


who: head-addition
package: scribble-lib
source: scribble-doc/scribblings/scribble/core.scrbl:1860:17
desc:
  Added in version 1.38.

Thanks,

Sorawee (Oak)

[Ben Greenman]

> It would be nice if I don’t have to modify scribble-lib, or, failing that,
> avoid touching documenting forms. Isn’t it possible for history to know
> which defform it’s under?

A history might not appear under a defform (for better or worse).

Maybe it's easier to give a list of links to the new history items. A
patch to @history could make an index tag ... something like
"h:7.4.0.3:hashtables" ... and then the search box might be good
enough to build a list of links.