Opened 2 years ago

Last modified 7 weeks ago

#29018 new enhancement

Improve documentation of m4/sage_spkg_configure.m4

Reported by: mkoeppe Owned by:
Priority: major Milestone: sage-9.7
Component: documentation Keywords:
Cc: dimpase, mjo Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: #28788 Stopgaps:

Status badges

Description

This ticket improves the documentation of the m4 macros provided by m4/sage_spkg_configure.m4.

Change History (9)

comment:1 Changed 2 years ago by mkoeppe

See also #26668

comment:2 Changed 2 years ago by mjo

I noticed this too but hadn't gotten around to it. I think now that a few people have a feel for how this works, we should rewrite the comment in sage_spkg_configure.m4. What's there is dubious, for example:

#   The macro takes five arguments.  The first, PACKAGE-NAME, is simply the
#   base name of the SPKG.  The first two arguments, both optional,
#   implement two different kinds of checks (the first of which is more
#   common).

What first two arguments? Is PACKAGE-NAME included in that?

#   The next argument (which is less commonly needed) is an optional list of

This "next" depends on me knowing what the first two arguments are that it's talking about, and I don't.

# ...  The last argument is again commands that
#   are always run, but after the checks are performed (or if they are not
#   performed):
#
#   - CHECK - this should implement a test for whether the package is already
#   ...

Last? Did we get all five? And why does the paragraph about the *last* argument then segue into a bullet list discussing all-but-one of them?

In short, I think we should drop the exposition from the top, and start with the bullet list, from...

The macro takes five arguments:

  • PACKAGE-NAME (required) ...
  • CHECK (optional) ...
  • REQUIRED-CHECK (optional) ...
  • etc.

and then the discussion about those arguments should come after we know what they are. In particular the arguments can then be mentioned by name and position, so the reader knows exactly which argument we're talking about.

comment:3 Changed 2 years ago by mkoeppe

  • Dependencies set to #28788

It should be checked whether #28788 added sufficient documentation.

comment:4 Changed 2 years ago by mkoeppe

  • Milestone changed from sage-9.1 to sage-9.2

pushing these forward to 9.2

comment:5 Changed 21 months ago by mkoeppe

  • Milestone changed from sage-9.2 to sage-9.3

comment:6 Changed 15 months ago by mkoeppe

  • Milestone changed from sage-9.3 to sage-9.4

Setting new milestone based on a cursory review of ticket status, priority, and last modification date.

comment:7 Changed 10 months ago by mkoeppe

  • Milestone changed from sage-9.4 to sage-9.5

comment:8 Changed 5 months ago by mkoeppe

  • Milestone changed from sage-9.5 to sage-9.6

comment:9 Changed 7 weeks ago by mkoeppe

  • Milestone changed from sage-9.6 to sage-9.7
Note: See TracTickets for help on using tickets.