PG Author Guide

[Alex-Jordan]

In one of the developer meetings (maybe a month ago?) I suggested using PreTeXt to create a PG author guide that could ship with a WW distribution. I've initialized such a project here: https://github.com/Alex-Jordan/pg-author-guide And you can see its HTML output here: https://alex-jordan.github.io/pg-author-guide/.

In the repo, you have .pg files (in the assets folder) and they are simultaneously included as code to look at and processed into live embedded problems. (Well, this is not true right now. But once PTX is using the standalone renderer, it will be.) I didn't include comments in these two samples, but you could. Instead I wrote explanatory comments in the paragraphs surrounding the code and the embedding.

Maybe this overlaps with #811?

What do people think about having a PG reference like this instead of the wiki?

[dlglin]

With the various work being done on updating sample problems I think we need to agree on some coding standards. That way all of our new resources can be consistent.

The first thing I noticed is that Alex is loading PGbasicmacros.pl, where I'm used to loading PGstandard.pl. Also, should we be pushing for PGcourse.pl to be added last in every problem?

I have started a page on the wiki to collect our decisions on these types of things: https://webwork.maa.org/wiki/Authoring_Best_Practices

Some of the things there are my suggestions. If the group disagrees feel free to change them.

[Alex-Jordan]

The first thing I noticed is that Alex is loading PGbasicmacros.pl,

That's just a mistake I made typing without thinking. And recently editing PGbasicmacros.pl because it was in my head.

[pstaabp]

@Alex-Jordan I like this, especially the ability to render the problem dynamically--definitely an improvement over what I'm working on with #811. I think these could be complementary if this is just a getting started guide and not include all of the sample problems that we currently have. And clearly, we can link between the two.

[Alex-Jordan]

Is there a reason why a problem file shouldn't just automatically load PGstandard.pl and PGML.pl (which loads MathObjects.pl) all the time? Automatically, first, before any loadMacros() calls?

For new authors, it's not great that even the most bare bones demonstration exercises require macro libraries to be explicitly loaded.

[pstaabp]

We've talked about automatically adding macros whenever loadMacros is called and it gets complicated. Seems okay at the problem level, but since loadMacros is called inside other macros and there's of recursion there or at the least loading some macros multiple times.

[Alex-Jordan]

We've talked about automatically adding macros whenever loadMacros is called and it gets complicated. Seems okay at the problem level, but since loadMacros is called inside other macros and there's of recursion there or at the least loading some macros multiple times.

I'm not sure we are talking about the same thing. I am effectiveely suggesting that DOCUMENT; would call loadMacros("PGstandard,pl", "PGML.pl");. Nothing about loadMacros() that are written in the PG file.