Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation of m4/sage_spkg_configure.m4 #29018

Open
mkoeppe opened this issue Jan 15, 2020 · 6 comments
Open

Improve documentation of m4/sage_spkg_configure.m4 #29018

mkoeppe opened this issue Jan 15, 2020 · 6 comments

Comments

@mkoeppe
Copy link
Contributor

mkoeppe commented Jan 15, 2020

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

Depends on #28788

CC: @dimpase @orlitzky

Component: documentation

Issue created by migration from https://trac.sagemath.org/ticket/29018

@mkoeppe mkoeppe added this to the sage-9.1 milestone Jan 15, 2020
@mkoeppe
Copy link
Contributor Author

mkoeppe commented Jan 16, 2020

comment:1

See also #26668

@orlitzky
Copy link
Contributor

comment:2

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.

@mkoeppe
Copy link
Contributor Author

mkoeppe commented Feb 10, 2020

comment:3

It should be checked whether #28788 added sufficient documentation.

@mkoeppe
Copy link
Contributor Author

mkoeppe commented Feb 10, 2020

Dependencies: #28788

@mkoeppe
Copy link
Contributor Author

mkoeppe commented Apr 14, 2020

comment:4

pushing these forward to 9.2

@mkoeppe mkoeppe modified the milestones: sage-9.1, sage-9.2 Apr 14, 2020
@mkoeppe mkoeppe modified the milestones: sage-9.2, sage-9.3 Aug 29, 2020
@mkoeppe
Copy link
Contributor Author

mkoeppe commented Feb 13, 2021

comment:6

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants