racket / scribble Goto Github PK

racketblock throws away the original format of numbers in code, replacing them with their equivalent decimal representation.

For instance, this example produces a document with 255 instead of #xff:

#lang scribble/base
@(require scribble/manual)

@racketblock[#xff]

Goal: pages on docs.racket-lang.org should have a button labeled "Edit on GitHub" that opens the scribble file that generated the HTML file that's displaying the button.

This is an issue and not a PR because I'm not sure how to implement it.

Idea 1 (the dream) change Scribble to automatically add "edit on github" links to the drop-down that appears when you click headings (just below "link to this section"). Guess this would only work for cloned packages.

Idea 2 (the less-wild dream) implement a --github <url> flag for the scribble command that uses the given url to generate the "edit on github" links for every page title / section.

Idea 3 (the easy-to-hack) put an @github-link[url] function in a scriblib library. Documentation authors need to explicitly call this function to put a button on their pages. (Instead of a button, maybe add a keyword to @section or @title)

. . . but it is in the docs.

examples from scribble/example does not preserve the 'paren-shape syntax property, and presumably drops other syntax properties as well. Given the following program:

#lang scribble/manual
@(require scribble/example)
@(examples (syntax-property #'[1 2 3] 'paren-shape))

…it produces the following output:

> (syntax-property #'[1 2 3] 'paren-shape)
#f

This is not due to scribble/manual, because the following program works as expected:

@(println (syntax-property #'[1 2 3] 'paren-shape))
; => #\[

When rendered with raco scribble --html file.scrbl, the scribble file below produces the following table of contents:

    A SecA
      1 SubAA
        1.1 SubAAA
        1.2 SubAAB
      2 SubAB
        2.1 SubABA
        2.2 SubABB
    B SecB
    C SecC

I would expect the parent number to show up as a prefix of the subsections, so that SubAA would be numbered as A.1, and SubAAA would be numbered as A.1.1, and so on. This is the behaviour when no numberer is used, but as soon as a numberer is specified, the parent numbers stop appearing as part of the children numbers.

#lang scribble/manual
@require[scribble/core]
@(define my-numberer
   (make-numberer (λ (current parents)
                    (values (list-ref '("A" "B" "C" "D" "…")
                                      (sub1 current))
                            (add1 current))) 1))
@title{Foo}
@(table-of-contents)
@section[#:style (style #f (list my-numberer))]{SecA}
@subsection{SubAA}
@subsubsection{SubAAA}
@subsubsection{SubAAB}
@subsection{SubAB}
@subsubsection{SubABA}
@subsubsection{SubABB}
@section[#:style (style #f (list my-numberer))]{SecB}
@section[#:style (style #f (list my-numberer))]{SecC}

Example:

#lang scribble/base

@(require scribble/example)

@examples[#:no-prompt
(define x 3)
code:blank
x]

I expected the HTML output for this to contain a blank line between (define x 3) and x. Removing #:no-prompt restores the expected behavior. Using #:lang also works.

Can we add an example to define-footnote to the docs? I have no idea how to use it properly, and the documentation does not make it clear to me. I think Adding an example would help here.

Also, it might make sense to add a contract to define-footnote, because if the footnote-part-id field is not an id, such as in:

(define-footnote dynamic-instances-footnote (lambda () @note{Foobar}))

the error message leaks the implementation of define-footnote:

making #path:/Users/leif/src/r-feature-profile/paper/background.scrbl
background.scrbl:86:53: define: not an identifier, identifier with default, or keyword for procedure argument
at: ()
in: (define ((lambda () (note "Foobar")) . text) (do-footnote-part footnotes id))
compilation context...:
/Users/leif/src/r-feature-profile/paper/background.scrbl
context...:
/Users/leif/racket/racket/collects/racket/private/norm-define.rkt:46:33: simple-proto
/Users/leif/racket/racket/collects/racket/private/norm-define.rkt:134:33: general-proto
/Users/leif/racket/racket/collects/racket/private/stxloc.rkt:21:17: try-next
/Users/leif/racket/racket/collects/racket/private/stxloc.rkt:21:17: try-next
/Users/leif/racket/racket/collects/racket/private/norm-define.rkt:166:4: normalize-definition
/Users/leif/racket/racket/collects/racket/private/kw.rkt:839:2
try-next
/Users/leif/racket/racket/collects/syntax/wrap-modbeg.rkt:46:4
/Users/leif/racket/racket/collects/compiler/cm.rkt:346:0: compile-zo*
/Users/leif/racket/racket/collects/compiler/cm.rkt:561:26
/Users/leif/racket/racket/collects/compiler/cm.rkt:553:42
/Users/leif/racket/racket/collects/compiler/cm.rkt:518:0: maybe-compile-zo
/Users/leif/racket/racket/collects/compiler/cm.rkt:633:2: do-check
/Users/leif/racket/racket/collects/compiler/cm.rkt:672:15
/Users/leif/racket/racket/collects/compiler/..:113:23: loop
/Users/leif/racket/racket/collects/compiler/cm.rkt:633:2: do-check

What version of Racket are you using?

6.4.0.8

What program did you run?

raco pkg install https://github.com/jsmaniac/scribble-enhanced.git#e4f18d1

cond-block does not work when compiled by raco setup. I created a new package and added the following file in scribllings, and pushed it to a separate branch: https://github.com/jsmaniac/scribble-enhanced/blob/e4f18d127007d5b6bd3b198008becb498e784180/scribblings/scribble-enhanced.scrbl

#lang scribble/manual
@(require scribble/core
          scriblib/render-cond)
@(cond-block
  [else (paragraph (style #f (list))
                   "foo")])

When installed it gives this error:

> raco pkg install https://github.com/jsmaniac/scribble-enhanced.git#e4f18d1
…
match: no matching clause for (traverse-block #<procedure:.../render-cond.rkt:38:12>)
  context...:
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/racket/match/runtime.rkt:23:0: match:error
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/pkgs/scribble-lib/scribble/contract-render.rkt:58:0: r-part
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/pkgs/scribble-lib/scribble/contract-render.rkt:14:4: render method in .../contract-render.rkt:12:2
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/pkgs/racket-index/setup/scribble.rkt:1418:3
   .../parallel-do.rkt:390:17
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/setup/../racket/private/more-scheme.rkt:261:28
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/setup/parallel-do.rkt:435:20: loop

  context...:
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/setup/parallel-do.rkt:334:4: work-done method in list-queue%
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/setup/parallel-do.rkt:284:17
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/setup/parallel-do.rkt:238:4
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/pkgs/racket-index/setup/scribble.rkt:431:2: make-loop
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/pkgs/racket-index/setup/scribble.rkt:138:0: setup-scribblings
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/setup/setup-core.rkt:70:0: setup-core
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/setup/setup.rkt:65:3
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/pkg/main.rkt:17:0: setup
   (submod /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/pkg/main.rkt main): [running body]
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/pkg/raco.rkt: [traversing imports]
…

Here's the whole installation log

> raco pkg install https://github.com/jsmaniac/scribble-enhanced.git#e4f18d1
Querying Git references for scribble-enhanced at https://github.com/jsmaniac/scribble-enhanced.git#e4f18d1
Downloading repository https://github.com/jsmaniac/scribble-enhanced.git#e4f18d1
raco setup: version: 6.4.0.8
raco setup: platform: x86_64-linux [3m]
raco setup: installation name: snapshot
raco setup: variants: 3m
raco setup: main collects: /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects
raco setup: collects paths: 
raco setup:   /home/georges/.racket/snapshot/collects
raco setup:   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects
raco setup: main pkgs: /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/pkgs
raco setup: pkgs paths: 
raco setup:   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/pkgs
raco setup:   /home/georges/.racket/snapshot/pkgs
raco setup: links files: 
raco setup:   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/links.rktd
raco setup:   /home/georges/.racket/snapshot/links.rktd
raco setup: main docs: /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/doc/racket
raco setup: --- updating info-domain tables ---
raco setup: updating: /home/georges/.racket/snapshot/share/info-cache.rktd
raco setup: --- pre-installing collections ---
raco setup: --- installing foreign libraries ---
raco setup: --- installing shared files ---
raco setup: --- compiling collections ---
raco setup: --- parallel build using 4 jobs ---
raco setup: 3 making: <pkgs>/scribble-enhanced
raco setup: 3 making: <pkgs>/scribble-enhanced/scribblings
raco setup: --- creating launchers ---
raco setup: --- installing man pages ---
raco setup: --- building documentation ---
raco setup: 3 skipping: <planet>/cce/scheme.plt/4/1/scribblings/main.scrbl
raco setup: 1 skipping: <planet>/dherman/pprint.plt/4/4/pprint.scrbl
raco setup: 3 running: <pkgs>/scribble-enhanced/scribblings/scribble-enhanced.scrbl
raco setup: WARNING: duplicate tag: (index-entry (mod-path "debug"))
raco setup:  in: /home/georges/.racket/snapshot/pkgs/debug/debug/scribblings/debug.scrbl
raco setup:  in: /home/georges/.racket/snapshot/pkgs/mischief/mischief/scribblings/mischief.scrbl
raco setup: WARNING: duplicate tag: (mod-path "debug")
raco setup:  in: /home/georges/.racket/snapshot/pkgs/debug/debug/scribblings/debug.scrbl
raco setup:  in: /home/georges/.racket/snapshot/pkgs/mischief/mischief/scribblings/mischief.scrbl
raco setup: 3 rendering: <pkgs>/racket-index/scribblings/main/user/local-redirect.scrbl
raco setup: 2 rendering: <pkgs>/racket-index/scribblings/main/user/release.scrbl
raco setup: 1 rendering: <pkgs>/scribble-enhanced/scribblings/scribble-enhanced.scrbl
raco setup: 0 rendering: <pkgs>/racket-index/scribblings/main/user/search.scrbl
match: no matching clause for (traverse-block #<procedure:.../render-cond.rkt:38:12>)
  context...:
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/racket/match/runtime.rkt:23:0: match:error
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/pkgs/scribble-lib/scribble/contract-render.rkt:58:0: r-part
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/pkgs/scribble-lib/scribble/contract-render.rkt:14:4: render method in .../contract-render.rkt:12:2
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/pkgs/racket-index/setup/scribble.rkt:1418:3
   .../parallel-do.rkt:390:17
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/setup/../racket/private/more-scheme.rkt:261:28
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/setup/parallel-do.rkt:435:20: loop

  context...:
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/setup/parallel-do.rkt:334:4: work-done method in list-queue%
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/setup/parallel-do.rkt:284:17
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/setup/parallel-do.rkt:238:4
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/pkgs/racket-index/setup/scribble.rkt:431:2: make-loop
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/pkgs/racket-index/setup/scribble.rkt:138:0: setup-scribblings
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/setup/setup-core.rkt:70:0: setup-core
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/setup/setup.rkt:65:3
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/pkg/main.rkt:17:0: setup
   (submod /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/pkg/main.rkt main): [running body]
   /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/pkg/raco.rkt: [traversing imports]
raco setup: 1 rendering: <pkgs>/racket-index/scribblings/main/user/start.scrbl
raco setup: --- installing collections ---
raco setup: --- post-installing collections ---
raco setup: --- summary of errors ---
raco setup: error: during building docs for <pkgs>/scribble-enhanced/scribblings/scribble-enhanced.scrbl
raco setup:   match: no matching clause for (traverse-block #<procedure:.../render-cond.rkt:38:12>)
raco setup:     context...:
raco setup:      /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/racket/match/runtime.rkt:23:0: match:error
raco setup:      /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/pkgs/scribble-lib/scribble/contract-render.rkt:58:0: r-part
raco setup:      /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/pkgs/scribble-lib/scribble/contract-render.rkt:14:4: render method in .../contract-render.rkt:12:2
raco setup:      /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/pkgs/racket-index/setup/scribble.rkt:1418:3
raco setup:      .../parallel-do.rkt:390:17
raco setup:      /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/setup/../racket/private/more-scheme.rkt:261:28
raco setup:      /nix/store/kkxy912zqmz950vc4kdgsq39rfvgpz29-racket-6.4.0.8/share/racket/collects/setup/parallel-do.rkt:435:20: loop
raco setup:   
.raco-wrapped pkg install: packages installed, although setup reported errors

Trying to build this test document:

#lang scribble/base

@(require scribble/manual)

Hello my name is @racket[#:test].

@section[#:tag "foo"]{Two}

Foobar

@secref["foo" #:doc #f]

fails with this error because the #:doc argument contract doesn't allow #f. I think the implementation contract is wrong here.

secref: contract violation
  expected: module-path?
  given: #f
  in: the #:doc argument of
      (->*
       (string?)
       (#:doc
        module-path?
        #:tag-prefixes
        (or/c #f (listof string?))
        #:underline?
        any/c)
       element?)
  contract from: 
      <pkgs>/scribble-lib/scribble/base.rkt
  blaming: /tmp/test.scrbl
   (assuming the contract is correct)
  at: <pkgs>/scribble-lib/scribble/base.rkt:583.2
  context...:
   /home/asumu/plt/racket-git/racket/collects/racket/contract/private/blame.rkt:143:0: raise-blame-error16
   /home/asumu/plt/racket-git/racket/collects/racket/contract/private/arrow-val-first.rkt:328:5: mk-call
   /home/asumu/plt/racket-git/racket/collects/racket/contract/private/arrow-val-first.rkt:325:3
   /tmp/test.scrbl: [running body]
   ...cket/cmdline.rkt:179:51
   /home/asumu/plt/racket-git/extra-pkgs/scribble/scribble-lib/scribble/run.rkt: [running body]

Consider a project that gathers multiple scribble/lp2 files into a single document. For TOC / navigation purposes, the names of the chunk blocks are treated like section titles. But unlike section, subsection, et al., they don't obey the #:tag-prefix setting, which means that to make things index correctly, you have to manually assign unique names to every chunk in the project.

Rendering

@verbatim["`(+ 1 2)"]

with scribble --pdf causes the backtick to be displayed as a curly left single quote instead of a backtick.

The documented contract is

(struct part-start (depth tag-prefix tags style title)
  #:extra-constructor-name make-part-start)
  depth : integer?
  tag-prefix : (or/c #f string?)
  tags : (listof string?)
  style : style?
  title : content?

while the actual contract on the constructor is:

      (->
       integer?
       (or/c #f string?)
       (listof tag?)
       style?
       content?
       part-start?)

Note contracts on tags.

When a scribble file for package documentation contains footnotes (from scriblib/footnote), building that documentation with raco fails in contract-render.rkt:

$ raco pkg install
...
match: no matching clause for (traverse-block #<procedure:...lib/footnote.rkt:78:5>)
  context...:
   /Applications/Racket v6.4/collects/racket/match/runtime.rkt:23:0: match:error
   /Applications/Racket v6.4/share/pkgs/scribble-lib/scribble/contract-render.rkt:62:0: r-blocks
   /Applications/Racket v6.4/share/pkgs/scribble-lib/scribble/contract-render.rkt:58:0: r-part
   /Applications/Racket v6.4/share/pkgs/scribble-lib/scribble/contract-render.rkt:14:4: render method in .../contract-render.rkt:12:2
   /Applications/Racket v6.4/share/pkgs/racket-index/setup/scribble.rkt:1418:3

Steps to reproduce:

• Create a new package: raco pkg new foo
• Edit foo/scribblings/foo.scrbl to add the following lines to the end:

@require[scriblib/footnote]
@define-footnote[footnote footnote-part]

Hello world@footnote{This is a footnote}

@footnote-part[]

• Run cd foo && raco pkg install and the above error occurs
  • The same failure does not occur if just using scribble foo.scrbl directly

Shouldn't there be a title argument?

(book-location [#:edition edition
                #:publisher publisher]) → element?
  edition : any/c = #f
  publisher : any/c = #f

When citations from bibtex contain authors with middle names or initials, the citations include the middle names/initals.

For example, see the Scribble document at: https://gist.github.com/bluephoenix47/dc18cfba6a91f4797490.

When rendered to PDF, the citation using autobib renders without the middle initial, while the citation using bibtex renders with the middle initial.

This program:

#lang scribble/base
@(require scriblib/footnote)
@(define-footnote footnote footnote-part)
abc@footnote{abc}

raises this error:

$ scribble --pdf tmp.scrbl
hash-ref: no value found for key
  key: (generated-tag)
  context...:
   /Users/robby/git/plt/extra-pkgs/scribble/scribble-lib/scribble/core.rkt:605:0: tag-key
   /Users/robby/git/plt/extra-pkgs/scribble/scribble-lib/scribble/core.rkt:24:0: resolve-get/where
   /Users/robby/git/plt/extra-pkgs/scribble/scribble-lib/scribble/core.rkt:62:0: resolve-get
   /Users/robby/git/plt/extra-pkgs/scribble/scribble-lib/scribble/base-render.rkt:758:4: resolve-content method in render%
   /Users/robby/git/plt/extra-pkgs/scribble/scribble-lib/scribble/base-render.rkt:758:4: resolve-content method in render%
   /Users/robby/git/plt/extra-pkgs/scribble/scribble-lib/scribble/base-render.rkt:758:4: resolve-content method in render%
   /Users/robby/git/plt/extra-pkgs/scribble/scribble-lib/scribble/base-render.rkt:758:4: resolve-content method in render%
   /Users/robby/git/plt/extra-pkgs/scribble/scribble-lib/scribble/base-render.rkt:758:4: resolve-content method in render%
   /Users/robby/git/plt/extra-pkgs/scribble/scribble-lib/scribble/base-render.rkt:758:4: resolve-content method in render%
   /Users/robby/git/plt/extra-pkgs/scribble/scribble-lib/scribble/base-render.rkt:725:4: resolve-flow method in render%
   /Users/robby/git/plt/extra-pkgs/scribble/scribble-lib/scribble/base-render.rkt:713:4: resolve-part method in render%
   loop
   /Users/robby/git/plt/extra-pkgs/scribble/scribble-lib/scribble/base-render.rkt:705:4: resolve method in render%
   /Users/robby/git/plt/extra-pkgs/scribble/scribble-lib/scribble/render.rkt:33:0: render57
   /Users/robby/git/plt/racket/collects/racket/contract/private/arrow-val-first.rkt:397:3
   /Users/robby/git/plt/extra-pkgs/scribble/scribble-lib/scribble/run.rkt: [running body]

This program worked in 5.3.3, but not in 5.3.4.

Here is an example document that illustrates the issue:

#lang scribble/manual

@(require scribble/example)

@examples[#:lang racket
(require racket/gui/base
         ffi/unsafe
         ffi/unsafe/define)
(define cairo-lib
  (ffi-lib #f))
(define-ffi-definer define-cairo
                    (ffi-lib #f))
(define-cairo cairo-create
  (_fun _pointer -> _pointer)
  #:c-id cairo_create)
]

If you produce HTML output from this, the indentation of the cairo-lib definition and the cairo-create definition are both off. The indented lines are shown with no indentation. Removing the #:lang racket argument restores the correct indentation behavior.

PRE-CONDITIONS

1. The screen is large enough that the margin notes appear on the margin instead of interspersed in the text.

2. There are two margin notes too near to one another.

CURRENT BEHAVIOR

The margin notes overlap, making the text unreadable:

EXPECTED BEHAVIOR

The second margin note goes under the first margin note, with no overlap.

SUGGESTED SOLUTION

Tufte CSS has the behavior I expect. It achieves it by a small hack: float: right; clear: right; margin-right: -<width>;.

If you agree this is an issue I can work on a Pull Request.

When a library requires and re-provides an identifier without modification, it is normally linked back to the original in documentation for files that require the library for-label. This behaviour is however broken when the chain of require and re-provide is going through a submodule. To test this, install the following package (I guessed the issue number wrong when naming the github repo…):

raco pkg install https://github.com/jsmaniac/example-bug-track-submodule-issue43.git#40c26708c8bec0041a1df444775d6f55161b9e5a

The package consists of three files:

other.rkt:

#lang racket/base
(module m racket/base
  (require syntax/stx)
  (provide (all-from-out syntax/stx)))

main.rkt:

#lang racket/base
(require (submod "other.rkt" m))
(provide (all-from-out (submod "other.rkt" m)))

scribblings/example-bug-track-submodule.scrbl:

#lang scribble/manual
@(require (for-label example-bug-track-submodule
                     racket/base))
@title{example-bug-track-submodule}
@author{georges}
@defmodule[example-bug-track-submodule]

The @racket[stx-map] function is re-provided from @racketmodname[syntax/stx].

On the last line of the scribble file, the @racket[stx-map] is not linked to the syntax/stx library's documentation, and causes the following warning:

raco: --- building documentation ---
raco: 1 running: <pkgs>/example-bug-track-submodule/scribblings/example-bug-track-submodule.scrbl
raco: WARNING: undefined tag in <pkgs>/example-bug-track-submodule/scribblings/example-bug-track-submodule.scrbl:
raco:  ((lib "example-bug-track-submodule/main.rkt") stx-map)

If the code in other.rkt is moved out of the submodule, and main.rkt is adjusted accordingly, then the warning disappears and the @racket[stx-map] becomes a link to the syntax/stx library's documentation. This can be tested using the without-submod branch of that package:

raco pkg remove example-bug-track-submodule-issue43
raco pkg install https://github.com/jsmaniac/example-bug-track-submodule-issue43.git#9747adce0f66bf2a60b58f86b51a0d39c24c0d4b

Even this simple usage of eval:check fails:

#lang racket/base
(require scribble/eval)
(interaction (eval:check #t #t))

eval: example result check failed in: #t

What's wrong?

#lang scribble/manual

@(require (for-label scribble/lp scribble/lp2 scribble/private/lp))
See also @racket[chunk] and @racket[CHUNK] from @racketmodname[scribble/lp2].

When running the file above through raco setup, it gives the following warning, and the identifiers are not hyperlinked to their documentation (they are underlined in red instead).

.raco-wrapped: WARNING: undefined tag in <pkgs>/foo/scribblings/foo.scrbl:
.raco-wrapped:  ((lib "scribble/private/lp.rkt") CHUNK)
.raco-wrapped:  ((lib "scribble/private/lp.rkt") chunk)

I suspect this has to do with the use in scribble-doc/scribblings/scribble/lp.scrbl of one of these constructs:

• @title[#:tag "lp" …]{Literate Programming}
• @defmodulelang[scribble/lp2 #:use-sources (scribble/lp)]{…}

If I have a main.scrbl, written:

@fn-a[]

@section{A section}
@fn-b[]

fn-a would be called first, and then fn-b.

However, if I extract the section to a file, so I have two files:

;;; main.scrbl
@fn-a[]

@include-section{section.scrbl}

;;; section.scrbl
@title{A section}
@fn-b[]

fn-b would be called first, and then fn-a.

However, they really should be called in the same order. In main.scrbl I might have something that modify a racket parameter (pinning the timezone in gregor, for example), and I would want those parameters get reflected in all sections.

I have a draft code that uses dynamic-require to solve this problem. However, I don't know whether it's general enough to be merged here:

(define (include-section* stx mod)
  (let* ([stx-path (syntax-source stx)]
         [mod-path (simplify-path (build-path stx-path 'up mod))])
    (dynamic-require `(file ,(path->string mod-path)) 'doc)))

(wrap-with-syntax include-section include-section*)

Where wrap-with-syntax is:

(define-syntax (wrap-with-syntax stx)
  (syntax-case stx ()
    [(_ name func)
     #'(define-syntax (name stx)
         (syntax-case stx () [(_ . t) #`(func (syntax #,stx) . t)]))]))

What Racket version are you using?

6.4.0.15

What program did you run?

#lang scribble/lp2

@chunk[<bbb>
       1]

@chunk[<*>
       '(<bbb> . yyy)]

What was the expected output ?

'(1 . yyy)

What happened instead?

'(<bbb> . yyy)

It seems that scribble traverses only proper lists. #(<bbb> yyy), #&(<bbb> yyy) and #hash([<bbb> . yyy]) do not work either.

It would be nice to have chunks substituted inside all s-expression primitives.

The module scribble/html does not export any structures.
That implies that it is not possible to do anything to the html
besides calling functions already defined in scribble/html

Consider this example:

#lang at-exp racket
(require scribble/html)

(define some-html @h2[id: "foo"]{bar})
; (element 'h2 '((id . "foo")) '("bar") #f)

(element-tag some-html)   ;; element-tag is unknown

(match some-html
  [(element tag atts contents ?)  ;; element is unknown
   tag])

I suspect simply adding element to the exports won't be enough,
since scribble/html defines a "smart constructor" named element
thus overriding the name.

This is the relevant file: https://github.com/racket/scribble/blob/master/scribble-html-lib/scribble/html/xml.rkt

acmart.cls uses the caption and manyfoot packages. These conflict with scriblib/figure and scriblib/footnote.

1. scriblib/figure uses the ccaption package. Both ccaption and caption define a \captionwidth command.
2. Both scriblib/footnote and manyfoot define a \Footnote command

I can see how to get around the 2nd problem --- scribble/acmart can provide its own @note{} function using manyfoot, or scriblib/footnote can use a different name than \Footnote

I don't know what to do about the second problem. @dvanhorn have you put figures in a scribble/acmart document?

Example program using scriblib/figure. To see the error I'm talking about, run scribble --latex file.tex; pdflatex file.tex.

#lang scribble/acmart
@require[scriblib/figure]

@title{Title}
@author{Anon}
@maketitle[]

@figure["fig:1" "Figure 1"]{ Hello I am a Figure }

As seen by this stack overflow question: http://stackoverflow.com/questions/34888125/change-font-color-in-scribble-html-backend/34909050#34909050

The only way to change the text color (or highlighting) is to drop into the backend and color it there. We really should be able to change this with scribble. Perhaps using the same API as the pict library.

(If we don't want to have a dedicated color selection, we should then at least have the ability to add some semantic meaning which may change the color, like a Warning Color which would be red.)

When a figure placed between two paragraphs in Scribble source code is not rendered between those two paragraphs in the output PDF, an extra newline is inserted between those two paragraph. This doesn't seem like the correct behavior.

Consider the Scribble document: https://gist.github.com/bluephoenix47/8299bdee5b4195ca8f8e

When rendered to a PDF, an extra newline is inserted between the second and third paragraphs.

scribble-lib/scribble/private/manual-style.rkt contains the following lines:

(provide/contract
  …
  [inset-flow (() () #:rest (listof pre-content?) . ->* . nested-flow?)]
  …)

but the documentation uses this signature:

(inset-flow pre-flow ...) → nested-flow?
  pre-flow : pre-flow?

The generated HTML is not responsive, IR won't look good on mobile devices.

When documenting a module in a package, I get different behavior depending on whether I import the module with (for-label "mod.rkt") or with (for-label collect/mod). In particular, in the first case, many of the hyperlinks in the generated html are missing and underlined in red. It works as expected when using the second require. This is misleading because the examples in the documentation (how-to.scrbl) requires modules for-label as path strings.

Example in a package 'scrib_test':

File doc.scrbl

#lang scribble/manual

@(require (for-label racket
            "mod.rkt"))

@defmodule[scrib_test/mod]

@defproc[(some-fun [x any/c])
         string?]{fun}

File mod.rkt

#lang racket

(provide some-fun)

(define (some-fun x)
  "fun")

Before indentation:

#lang scribble/text
@list{
foo
}

After:

#lang scribble/text
@list{
 foo
}

Note the space inserted before "foo", which changes the data represented by this at-expression. Since whitespace is meaningful inside curly braces, the indenter should always leave those sections alone.

At first I found it more convenient if the sidebar (containing table of contents and navigation box) stays in view while scrolling the main content.

I tried modifying the related css file (manual-style.css) by changing the "position" attribute from "absolute" to "fixed".

$ git diff
diff --git a/scribble-lib/scribble/manual-style.css b/scribble-lib/scribble/manual-style.css
index 1327c9a..0fcd65b 100644
--- a/scribble-lib/scribble/manual-style.css
+++ b/scribble-lib/scribble/manual-style.css
@@ -182,7 +182,7 @@ a:hover {
 }
 
 .navsettop {
-    position: absolute;
+    position: fixed;
     top: 0;
     left: 0;
     margin-bottom: 0;
@@ -393,7 +393,7 @@ a:hover {
 /* Table of contents, left margin */
 
 .tocset {
-    position: absolute;
+    position: fixed;
     float: none;
     left: 0;
     top: 0rem;

But soon I noticed that if the table of contents in the sidebar gets too long while the "position" is "fixed", the sidebar won't scroll at all. So the bottom part of of the sidebar could never be seen.

Is there a way to deal with this? I'm not sure if css can do this, but an idea is to add a floating "go to top of page" button in case that the sidebar is scrolled out of sight. The point is to make it more convenient for users who wants to find and click a link in the table-of-contents within the sidebar.

See florence/cover#91

Roughly the issue is that chunks in scribble/lp don't get registered as run by cover. Perhaps the issue is that the code that gets run has had its source locations stripped by one of scribble/lp's macros?

I don't know if this is normal or just a peculiarity of Debian or Ubuntu packaging, but in the /usr/share/doc/racket there are many blueboxes.rktd.gz files. It seems like the compressed files are not being read when running make-bluueboxes-cache.

I tested by copying /usr/share/doc/racket/reference/blueboxes.rktd.gz to my desktop, and running

(define tag (xref-binding->definition-tag (load-collections-xref) #'dict-ref 0)) 
(fetch-blueboxes-strs tag #:blueboxes-cache 
    (make-blueboxes-cache #t #:blueboxes-dirs (list (string->path "/home/don/desktop/"))))

When the blueboxes file is compressed, this results in #f, but when the blueboxes file is uncompressed the result is what you would hope:

'("procedure"
  "(dict-ref dict key [failure-result]) -> any"
  "  dict : dict?"
  "  key : any/c"
  "  failure-result : (failure-result/c any/c)"
  "                 = (lambda () (raise (make-exn:fail ....)))")

I came across this while trying to figure out why the xrepl ,describe command wasn't showing the documentation for many commands.

#lang scribble/lp2
@itemlist[
 @item{Foo
  @itemlist[
 @item{Bar}]}]

The file above should likely indent as:

#lang scribble/lp2
@itemlist[
 @item{Foo
  @itemlist[
   @item{Bar}]}]

Another example which does not mix [ and {:

@itemlist[
 @item[
 "Foo"
 @itemlist[
 @item["Bar"]]]]

which should indent as:

@itemlist[
 @item[
  "Foo"
  @itemlist[
   @item["Bar"]]]]

When I added footnotes below my section 1.1, the next section appears as "1.3" rather than "1.2".

This happens only if I put the text of section 1.1 within the file of the upper level "section 1". If I put the content of 1.1 in a separate file and include it with the "@include-section" syntax, this won't happen. The next section would show as section 1.2, as expected.

See in the screenshot below, no section 2.5, 2.7, 2.9, 2.11 is present. All because I put an footnote area below their preceding section.

Running the file manual.scrbl below through scribble --html --dest docs/. +m --redirect-main http://docs.racket-lang.org/ manual.scrbl does not generate links for the display identifiers inside @code and @codeblock.

Just changing #lang scribble/lp2 to #lang scribble/manual makes them clickable in the resulting html.

#lang scribble/lp2

@(require scribble/doclang
          scribble/manual
          scribble/html-properties
          (for-label (only-meta-in 0 racket))
          (only-in scribble/private/lp chunk CHUNK))

@code[#:lang "racket"]{(display 42)}

@codeblock{
#lang racket
(display 42)
}

@chunk[<*> (void)]

If the document below is compiled with raco scribble --pdf file.scrbl, then the subsections of SecA are moved one level up (i.e. they are typeset as sections, not as subsections). When the HTML renderer is used, via raco scribble --html file.scrbl, the sections SubAA, SubAB and their children are correctly typeset in the table of contents as subsections of SecA (resp. subsubsections for their children).

If I remove the [#:style (style #f (list my-numberer))], then the LaTeX output is correct. Unfortunately, parts are not blocks, and there is no cond-part to go with cond-block and cond-element, do I cannot conditionally disable the numberer for LaTeX output.

#lang scribble/manual
@require[scribble/core]
@(define my-numberer
   (make-numberer (λ (current parents)
                    (values (format "~a" current)
                            (add1 current))) 1))
@title{Foo}
@(table-of-contents)
@section[#:style (style #f (list my-numberer))]{SecA}
@subsection{SubAA}
@subsubsection{SubAAA}
@subsubsection{SubAAB}
@subsection{SubAB}
@subsubsection{SubABA}
@subsubsection{SubABB}
@section[#:style (style #f (list my-numberer))]{SecB}
@section[#:style (style #f (list my-numberer))]{SecC}

Here's the diff between the generated good.tex and bad.tex. It shows that the sections SecA, SecB and SecC are not affected themselves, but the subsections are rendered with \sectionNewpage + \Ssection instead of the correct \Ssubsection.

460c460
< \Ssubsection{SubAA}{SubAA}\label{t:x28part_x22SubAAx22x29}
---
> \sectionNewpage
461a462
> \Ssection{SubAA}{SubAA}\label{t:x28part_x22SubAAx22x29}
464d464
< \Ssubsubsection{SubAAA}{SubAAA}\label{t:x28part_x22SubAAAx22x29}
465a466
> \Ssubsection{SubAAA}{SubAAA}\label{t:x28part_x22SubAAAx22x29}
468d468
< \Ssubsubsection{SubAAB}{SubAAB}\label{t:x28part_x22SubAABx22x29}
469a470
> \Ssubsection{SubAAB}{SubAAB}\label{t:x28part_x22SubAABx22x29}
472d472
< \Ssubsection{SubAB}{SubAB}\label{t:x28part_x22SubABx22x29}
473a474
> \sectionNewpage
474a476
> \Ssection{SubAB}{SubAB}\label{t:x28part_x22SubABx22x29}
476d477
< \Ssubsubsection{SubABA}{SubABA}\label{t:x28part_x22SubABAx22x29}
478a480
> \Ssubsection{SubABA}{SubABA}\label{t:x28part_x22SubABAx22x29}
480c482,484
< \Ssubsubsection{SubABB}{SubABB}\label{t:x28part_x22SubABBx22x29}
---
>
>
> \Ssubsection{SubABB}{SubABB}\label{t:x28part_x22SubABBx22x29}

I just updated my minimal racket installation from 6.7.0.1 to 6.7.0.3, and I noticed that raco setup --avoid-main gives an error, saying that it can't overwrite the manual-fonts.css manual-racket.css etc. files.

I checked their permissions, and it seems that all these files were -r--r--r-- for all packages (both those in ~/.racket from the catalog, and the linked packages). After doing
find /home/georges/.racket/ -name doc -print0 | xargs -0 chmod +w -R
and re-running raco setup --avoid-main, the new files correctly have the mode -rw-r--r--.

Is it possible that earlier versions placed the files with read-only attributes, and that the new version refuses to overwrite read-only files? Unless I'm mistaken, the directory itself is writable, so scribble could in principle remove the read-only files and replace them by the new ones.

When I try to include amssymb into my scribble files, I get an error message. One of the problems seems to be that \ulcorner, \urcorner, \llcorner, and \lrcorner are being re-defined.

To reproduce:

> echo "#lang scribble/base" > main.scrbl
> echo "\\\\usepackage{amssymb}" > style.tex
> scribble ++style style.tex --pdf main.scrbl

Also, amsmath causes similar problems.

I’ve come across some odd behavior when using make-eval-factory from scribble/eval to include Typed Racket modules in the produced evaluators. Specifically, TR complains about macros “from typed module used in untyped code”. This is probably best explained via example, so here’s a minimal version of the example I ran into that produces the problem:

#lang scribble/manual

@(require scribble/eval)

@(examples
  #:eval ((make-eval-factory #:lang 'typed/racket/base
                             '(typed/alexis/util/comparator)))
  (struct foo ())
  (: foo-compare (foo foo -> (U -1 0 1)))
  (define (foo-compare a b) 0)
  (define-comparison-predicates foo : foo foo-compare)
  (foo=? (foo) (foo)))

Type Checker: Macro define-comparison-predicates from typed module used in untyped code

However, if I require the module inside the evaluator, it all works fine:

@(examples
  #:eval ((make-eval-factory #:lang 'typed/racket/base))
  (require typed/alexis/util/comparator)
  (struct foo ())
  (: foo-compare (foo foo -> (U -1 0 1)))
  (define (foo-compare a b) 0)
  (define-comparison-predicates foo : foo foo-compare)
  (foo=? (foo) (foo)))

It seems that the way make-eval-factory requires the modules isn't compatible with TR. I think the reason for this is explained by this phrase in the documentation:

each module in mod-paths is also required into the top-level environment for each generated evaluator

The key is "top-level". I suppose the craziness TR does to support the top-level doesn't really work too well with this. Requiring the module manually is a viable workaround, but I wonder if this could be easily fixed (and why it occurs in the first place).

At the moment, the command-extras and command-optional style properties (for latex) only work for elements. This is a little problematic for flows that take multiple arguments. (Such as say, minipage, which has a begin/end form.

At the moment, you can sort of fake it with elements, but its really clunky. Say:

@elem[#:style (style "begin" (list (command-extras '("0.5\\textwidth"))))]{
 minipage}
Left Side
@elem[#:style (style "end" '())]{minipage}
@elem[#:style (style "begin" (list (command-extras '("0.5\\textwidth"))))]{
 minipage}
Right Side
@elem[#:style (style "end" '())]{minipage}

But it would be much cleaner to just do:

@nested[#:style (style "minipage" (list (command-extras '("0.5\\textwidth"))))]{
  Left Side}
@nested[#:style (style "minipage" (list (command-extras '("0.5\\textwidth"))))]{
  Right Side}

In the file run.rkt (in scribble-lib/scribble), there is a parameter for the current output directory that scribble is rendering too. (Called current-dest-directory). This parameter seems like it should be possible for the user to get a hold of (at least to read anyway), so that they can dynamically put files in that directory. (At least that is what @wilbowma seems interested in doing.)

When the following file is rendered with raco scribble --pdf file.scrbl, the sections SecA, SecB and SecC are still numbered using Arabic numbers in the PDF.

I think it would be better if the LaTeX/PDF output was consistent with the HTML one. The sections could be typeset as \section*, and have their number hardcoded in the title, or, possibly better, by redefining \thesection to the constant, pre-computed “number” and restoring it immediately after:

\let\oldthesection\thesection
\renewcommand{\thesection}{A}
\section{SecA}
\let\thesection\oldthesection

…

\let\oldthesection\thesection
\renewcommand{\thesection}{B}
\section{SecB}
\let\thesection\oldthesection

#lang scribble/manual
@require[scribble/core]
@(define my-numberer
   (make-numberer (λ (current parents)
                    (values (list-ref '("A" "B" "C" "D" "…")
                                      (sub1 current))
                            (add1 current))) 1))
@title{Foo}
@(table-of-contents)
@section[#:style (style #f (list my-numberer))]{SecA}
@subsection{SubAA}
@subsubsection{SubAAA}
@subsubsection{SubAAB}
@subsection{SubAB}
@subsubsection{SubABA}
@subsubsection{SubABB}
@section[#:style (style #f (list my-numberer))]{SecB}
@section[#:style (style #f (list my-numberer))]{SecC}

If I type stackoverflow.com into the Chrome omnibox without pressing enter a little "Press tab to search Stack Overflow" note pops up:

Now I can search StackOverflow directly without having to load the page, wait for the search box to render, navigate to the box, and type in my search. I just press tab and go. This happens without any configuration or effort on my behalf. I'd like it if the docs.racket-lang.org website did the same, as searching those docs is very common for me even outside DrRacket.

Apparently, this works through the OpenSearch standard. For Scribble to support this there would need to be a link in the generated HTML to an OpenSearchDescription XML document, as described in this StackOverflow question.

If I have the following scribble program:

#lang scribble/sigplan

@require[scribble/manual]

Paragraph
@racket[(some-racket-function name with arguments)]. This
paragraph also has a bunch of text so that we can get a good
sense of what the fill box is.

When I render it to a pdf, the arguments identifier gets split across to a new line, making:

I get that a chunk of @racket[...] code is in the text and might wrap, but splitting it in the middle of an identifier like this seems bad.

Hi there

How to open and build Scribble project?

In the code below, the (require 'm) fails. Interestingly, it is possible to require m from a sibbling submodule works, but (require (submod "." m)) doesn't work.

#lang scribble/lp2

@chunk[<*>
       (module m racket
         (define x 1)
         (provide x))
       (require 'm)                 ;; Fails with "require: unknown module" module name: #<resolved-module-path:'m>
       (require (submod "." m))     ;; Fails with "require: unknown module" module name: #<resolved-module-path:(submod 'scribble-lp-tmp-name m)>
       (module other racket
         (require (submod ".." m))) ;; Works.
       ]

CURRENT BEHAVIOR

In #lang racket, {braces} work the same as (parentheses) and expressions using either are indented the same:

#lang racket

(define foo
  `{(a)
    (b)})

(define foo-paren
  `((a)
    (b)))

In #lang at-exp, the @-expressions with {braces} are indented differently:

#lang at-exp racket

@foo{bar
 bar}

And that difference applies even to non-@-expressions with {braces}:

#lang at-exp racket

(define foo
  `{(a)
 (b)})

(define foo-paren
  `((a)
    (b)))

EXPECTED BEHAVIOR

Using #lang at-exp does not affect the indentation of non-@-expressions:

#lang at-exp racket

@foo{bar
 bar}

(define foo
  `{(a)
    (b)})

(define foo-paren
  `((a)
    (b)))

RELATED DISCUSSION

mbutterick/pollen#124

Do you think this makes sense? If so, how can I help turning this idea into code?

Hi,

Scribble includes a large block of HTML code in the headers of the generated document, along with CSS and JS files. It similarly includes a large number of LaTeX headers, and the PDF output can be considered a "compiled" form of the LaTeX code (thereby a derivative?).

The current license is the LGPL, and IIUC we're going to switch to MIT + Apache v2 at some point in the near future.

What impact do these blobs of HTML and LaTeX have on the license of the source document, and on the license of the generated HTML / LaTeX / PDF ?

I'm pretty sure that the HTML and LaTeX versions are tainted in some way. For example, the CSS files embed fonts, so it seems impossible to publish the HTML version online, and say that "this document is in the public domain / CC0", as this could implicitly cover the fonts, which are explicitly stated as being under the SIL Open Font License. I would guess that the generated LaTeX code is similarly tainted, at least in the sense that the portion of the preamble which is injected into the documentation is covered by Scribble's license, and distinguishing what parts are affected by it, and the distinction between what parts remain under the license of the original author seems vague, if at all possible.

It wouldn't be much of a stretch to have a literate program licensed under the GPL (not LGPL), therefore tainting both its source and documentation via linking, and tainting the fonts, which are embedded in the CSS files which are "linked" to the HTML file. This obviously sound like a legal swamp, and this example use case relies on terms like "linking" having no satisfying definition in the modern programming world, and the use of the GPL (which is not adapted to documentation) on a literate program. This is therefore not a very reasonable example, but hopefully it highlights some of the issues that the average "IANAL" developer may be concerned with, knowingly or not.

Could we therefore try to explicitly indicate what are the legal implications of writing and rendering documents with scribble, when using the default LaTeX prefix and the main HTML styles shipped with scribble (scribble/manual and scribble/base)?