Restructure the POD of macros #1244
Conversation
pstaabp
force-pushed
the
restructure-pod-macros
branch
3 times, most recently
from
ea9d812 to
52d9c92
Compare
pstaabp
force-pushed
the
restructure-pod-macros
branch
3 times, most recently
from
21d6afc to
daac4b1
Compare
For consistency the POD of macros have been updated so that there is a `=HEAD1 NAME` with the following structure: ``` macroName.pl - short description. ```
pstaabp
force-pushed
the
restructure-pod-macros
branch
from
daac4b1 to
39ce4ca
Compare
There was a problem hiding this comment.
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.
| @@ -193,10 +188,10 @@ sub ignore_order { | |||
|
|
|||
| =back | |||
There was a problem hiding this comment.
This line needs to be deleted. It is a =back without =over.
| @@ -13,7 +17,7 @@ =head1 DESCRIPTION | |||
|
|
|||
| Context('Boolean'); | |||
|
|
|||
| =head2 CONSTANTS | |||
| =head3 CONSTANTS | |||
There was a problem hiding this comment.
This jumps from head1 to head3 and skips head2 which should never be done. podchecker gives several warnings like *** WARNING: =head3 without preceding higher level at line 20 in file macros/contexts/contextBoolean.pl because of this. This also causes odd display issues in the sidebar of the generated HTML for the POD. Drop the =head3s to =head2s.
| @@ -82,7 +76,7 @@ =head1 USAGE | |||
| numebrs would be displayed in standard form. | |||
|
|
|||
|
|
|||
| =head1 LISTS IN ALTERNATE FORMAT | |||
| =head3 LISTS IN ALTERNATE FORMAT | |||
There was a problem hiding this comment.
This jumps from =head1 to =head3 also. Drop the =head3s to =head2.
| @@ -83,7 +78,7 @@ =head1 USAGE | |||
| would allow students to enter intervals in either format, but all | |||
| intervals would be displayed in standard form. | |||
|
|
|||
| =head1 Setting the alternate form as the default | |||
| =head3 Setting the alternate form as the default | |||
There was a problem hiding this comment.
This jumps from =head1 to =head3 also. Drop the =head3s to =head2.
| @@ -75,7 +73,7 @@ =head1 DESCRIPTION | |||
|
|
|||
| The last two digits for C<base64> are nonstandard. We want to avoid '+' and '/' here as they have arithmetic meaning. | |||
|
|
|||
| =head2 Sample PG problem | |||
| =head3 Sample PG problem | |||
There was a problem hiding this comment.
This jumps from =head1 to =head3 also. Drop the =head3s to =head2.
|
|
||
| =head1 NAME | ||
|
|
||
| SystemOfLinearEquationsProblemPCC.pl - |
There was a problem hiding this comment.
Remove the - at the end of this line. Either that or add something after it.
| @@ -1,25 +1,19 @@ | |||
|
|
|||
| =encoding utf8 | |||
|
|
|||
| =head1 NAME | |||
There was a problem hiding this comment.
Add =encoding utf8 back to this file. It is there for a reason. The POD uses unicode characters, and removing this line causes warnings.
| @@ -1,25 +1,21 @@ | |||
|
|
|||
| =encoding utf8 | |||
|
|
|||
| =head1 NAME | |||
There was a problem hiding this comment.
Also add =encoding utf8 back to this file.
|
|
||
| =head1 NAME | ||
|
|
||
| tableau_main_subroutines.pl - |
There was a problem hiding this comment.
Remove the - at the end of this line. Either that or add something after it.
| @@ -1,3 +1,5 @@ | |||
| # Note: this probably no longer works using CGI unless specifically set up. Deprecate? | |||
There was a problem hiding this comment.
As with all of these comments that you have added at the beginnings of files, remove it. Also, note that this should not be deprecated. It does take special set up (and always has), but it still has its uses and does still work. Of course it should never be used in a problem for a course, and should not be used in problems added to the OPL.
For consistency the POD of macros have been updated so that there is a
=head1 NAMEwith the following structure:Also, any method or function names will have the form:
This is helpful in conjunction with openwebwork/webwork2#2733 to extract information from the macro files.