improve package and simpledoc documentation

[mikestillman]

The documentation for packages, and the SimpleDoc format could be improved. I will edit this list with suggestions, things done, etc. Help would be welcome!

Here are some of the doc nodes for packages and documentation, and sometimes a few suggestions for things that should be changed. Perhaps these nodes should even be consolidated somehow.

• The node and package SimpleDoc
  • Have a getting started node, where one sees the basic use of SimpleDoc.
  • Have a node (currently the doc node) that describes the general format, and also how to do some common things (e.g. having a list of items, adding a URL link).
  • How to write math in a doc node
• The node Package
  • make sure SimpleDoc is linked to!
  • Similarly, packageTemplate should be visible from here
  • packageTemplate should include the end-- near the end of the file.
• The node packages
• The node creating a package
• The node an example of a package
  • should link to packageTemplate (in SimpleDoc)
  • Perhaps use doc rather than multidoc for doc here
• Node informing others about your package
  • Seems out of date.
• The node writing documentation -- Doesn't even mention SimpleDoc, or docTemplate. It should be based on SimpleDoc I think.
• The node conventions for documentation -- Also out of date.

[mahrud]

Do all of the above need to be documentation nodes written within Macaulay2? I'm wondering if using a more expressive format would make more sense.

[mikestillman]

@mahrud : What do you have in mind?

[mahrud]

Nothing specific, other than maybe unifying all the nodes you mentioned into one that is linked on the front page. I was just looking around, and it seems common to have separate formats for manuals (e.g. setup M2 with emacs, start a package, tutorials, etc.), language reference, and package documentation. It's not the same everywhere, of course. Here are a few examples from Go, Julia, Rust, and GAP.

[mahrud]

Weird issue: I can't figure out how to link to writing documentation or even the (document, List) node. The tags don't follow the typical Macaulay2Doc :: ... style and are something like Macaulay2Doc > The Macaulay2 language > packages > creating a package > document instead.

[DanGrayson]

TO document should work, but (document,List) is undocumented.

[mahrud]

What about writing documentation?

On Thu, Jun 4, 2020 at 11:01 AM Daniel R. Grayson notifications@github.com wrote:

TO document should work, but (document,List) is undocumented.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/Macaulay2/M2/issues/1220#issuecomment-638950200, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAYAPRWCQCEUXGDWOW7QKZ3RU7AN7ANCNFSM4NP5BWVQ .

[DanGrayson]

For that, use TO "writing documentation"

Actually, I was wrong: TO (document,List) and TO document would point to the same node.

[mahrud]

Among the three, only TO document seems to be working within package documentation.

On Thu, Jun 4, 2020 at 3:59 PM Daniel R. Grayson notifications@github.com wrote:

For that, use TO "writing documentation"

Actually, I was wrong: TO (document,List) and TO document would point to the same node.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/Macaulay2/M2/issues/1220#issuecomment-639113056, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAYAPRVIMT4SDE7QJG46CD3RVADJXANCNFSM4NP5BWVQ .

[DanGrayson]

Can you point me to an instance of the two not working?

[mahrud]

Well, writing documentation is never linked to outside of its parent section! Try checking out and installing from my SimpleDoc PR #1234 and looking at the top node:

writing documentation (missing documentation)

Alternatively, see this part of simpleDocFrob on the official documentation page:

 Each paragraph of text begins with "Text". The following line starts a sequence of Macaulay2 example input lines. However, see matrix(List) (missing documentation).

Or at the bottom:

directSum(List) (missing documentation) -- direct sum of modules or maps

[mahrud]

Do we still want people to use the document List function going forward, or should it be phased out? For instance, should "overview documentation template " be deleted?

[DanGrayson]

No, let people choose what they want.

I still think multidoc and doc should be merged, by the way.

[mahrud]

@mikestillman I'll close this as fixed in the PR above. If you have any other suggestions or anything is amiss, please reopen.