Restructure the POD of macros

[pstaabp]

For consistency the POD of macros have been updated so that there is a =head1 NAME with the following structure:

macroName.pl - short description.

Also, any method or function names will have the form:

=head2 function_name

This is helpful in conjunction with openwebwork/webwork2#2733 to extract information from the macro files.

[Alex-Jordan]

I'm trusting that this is only POD edits as advertised. I'm not actually reading over all the changes.

[drgrice1]

There are several changes that are needed.

Make sure that if a file has =encoding utf8 that that is NOT removed. Also, note that there is also a unicode character used in macros/parsers/parserLinearInequality.pl, and so that file should have =encoding utf8 added to the beginning. Please add that.

Go through all files that you added comments at the beginning regarding deprecation and such, and remove those comments. We could start a GitHub discussion about that, but it should not be added to the code.

[drgrice1]

By the way, one thing I noticed while looking at this pull request is that there is a very common misspelling in the POD of PG. The word SYNOPSIS is often spelled SYNPOSIS. The following files have this mispelled:

• lib/AnswerHash.pm
• lib/AnswerIO.pm
• lib/Applet.pm
• lib/Circle.pm
• lib/Fun.pm
• lib/Hermite.pm
• lib/Label.pm
• lib/Parser/Legacy/PGcomplexmacros.pl
• lib/VectorField.pm
• lib/WWPlot.pm
• lib/WeBWorK/PG/EquationCache.pm
• lib/WeBWorK/PG/ImageGenerator.pm
• lib/WeBWorK/PG/RestrictedClosureClass.pm
• lib/WeBWorK/PG/Translator.pm
• macros/PG.pl
• macros/answers/extraAnswerEvaluators.pl
• macros/core/PGanswermacros.pl
• macros/core/PGessaymacros.pl
• macros/deprecated/CofIdaho_macros.pl
• macros/deprecated/PGsequentialmacros.pl
• macros/graph/PGgraphmacros.pl
• macros/graph/PGstatisticsGraphMacros.pl
• macros/math/LinearProgramming.pl

It wouldn't hurt to fix that.

[pstaabp]

Changed the spelling of SYNOPSIS and fixed a number of other POD errors in modules seen using podchecker.

[drgrice1]

I think that you should be more careful with the choice of header levels. Those have meaning. You initially had an objective of putting methods and functions at the head2 level. That led to some bad things. Look over the changes carefully and revert things that shouldn't have been done.

Perhaps consider breaking this massive pull request up into a few files at a time also.

[pstaabp]

I think I'll split this up into smaller PRs and now that we have openwebwork/webwork#2759, I'll revert the changes from =head2 to =head1.

[pstaabp]

@drgrice1 I split off all of the perl modules in the lib/ directory and those are in #1264.

I tried to be more careful with the levels of the =head headers. There was also some cleanup of formatting of some macros (only in the POD).

Note: still a lot to be done. Some macros are bare of any documentation, but not sure those are worth putting effort into.

If this is still too large, I can split into two parts.

[drgrice1]

Clearly this pull request would not be so big if there were not so many changes made that shouldn't have been made to begin with.

[pstaabp]

@drgrice1 fixed all of your comments. I'll start a GitHub discussion with a list of many of the comments I put at the top of the macros.

[Alex-Jordan]

I opened several PRs that break this one down by folder. I thought it might help review things to do it in small doses. If it's fine to just continue with this PR, that's fine. And then in that case please ignore #1266 through #1273.

[pstaabp]

Closing in favor of #1266, #1267, #1268, #1269, #1270, #1271, #1272, #1273