racket / racket/draw

manual class sections lack a <h3> title

Open
#57 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Racket
Stars
19
Forks
24
PR merge metrics
No merged PRs in 30d

Description

Class sections lack a <h3> title

neither
@include-section["color-class.scrbl"] in https://github.com/racket/draw/blob/master/draw-doc/scribblings/draw/draw.scrbl
or @defclass/title[color% object% ()]{ in https://github.com/racket/draw/blob/master/draw-doc/scribblings/draw/color-class.scrbl
does not cause a title for the section to be generated

but the first section 1. Overview does have a title

https://github.com/racket/draw/blob/master/draw-doc/scribblings/draw/guide.scrbl
@title[#:tag "overview"]{Overview}


As I wrote this issue I found

This form is normally used to create a section to be rendered on its own HTML. The 'hidden style is used because the definition box serves as a title.

https://docs.racket-lang.org/scribble/doc-classes.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._defclass%2Ftitle%29%29

So maybe this is intentional?

I'd prefer a <h3> heading "6 class%" followed by the definition box but I'm guessing that adding @title[#:tag "color%"]{color%} is the wrong way to achieve this. (I'm assuming it is desirable)

The other option would be to change
(list* (title #:style 'hidden (to-element (decl-name decl)))
to
(list* (title #:style #f (to-element (decl-name decl)))
but that would also affect defmixin/title and definterface/title.


PS I noticed this because I went looking to click the title to find the manual source like I could do for section 1:
image

  • there is a 6.1 Equality heading
image
  • there is no 6 colour% heading
image

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with draw-doc/scribblings/draw/draw.scrbl, color-class.scrbl, and guide.scrbl to compare the generated class and section headings. Then inspect scribble/private/manual-class.rkt around the title construction and the Scribble manual documentation for defclass/title. Done means the intended class heading behavior is decided, implemented without unintentionally changing related forms, and reflected in the generated documentation.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.