Split up macros on PODViewer index page. #2615
Conversation
There was a problem hiding this comment.
There are two issues with this pull request.
The first is that this changes how the POD is organized inconsistent with how the pod generated by the bin/dev_scripts/generate-ww-pg-pod.pl script is organized (that is the pod displayed at https://webwork.maa.org/pod/).
The second is that the reorganization of the files into sub directories was not intended to be a visible categorization of macros. At least not initially. It was done more for development purposes to keep the pg/macros directory from being a completely unorganized mess with one long list of files. The organization that was done was not the most intuitive in terms of what macros are actually used for. For example, all macros that started with "parser" were just put in the "parsers" subdirectory, and all macros that started with "context" into the "contexts" subdirectory. Sorting purely by what the macro started with is not the best way to do that. The intent was to sort things better eventually. For example. the parserGraphTool.pl macro was later moved to the "graph" subdirectory. I am not sure that the organization is ready to be publicized in this way.
So this needs discussion first.
|
I think we are already publicizing the macro organization this way. The macros are currently sorted by what directory they are in, further that directory is printed in the link name. So knowing what directory a macro is in helps one find it in the long list of macros on the POD index (this mostly just splits that list apart). Though I do welcome more discussion on this to have a way that users can easily find the POD of a macro they are using or find a new macro they may want to use. |
This splits up the macros on the PODViwer index page to be grouped by their location in the `pg/macros` directory. In addition macros are listed before the libraries. The two macros not in a subdirectory, `PG.pl` and `PGcourse.pl`, are grouped with the pod in `pg/doc`. This makes finding the POD for a specific macro easier.
|
We are currently listing them with their directory for ease of location. The sorting will then list those in the same directory together. That is not exactly the same thing as a categorization. As I said, this needs discussion. In any case, my first point is more pressing. The dev script will need to be updated to match. That is if we decide we want this organization. |
This splits up the macros on the PODViwer index page to be grouped by their location in the
pg/macrosdirectory. In addition macros are listed before the libraries. The two macros not in a subdirectory,PG.plandPGcourse.pl, are grouped with the pod inpg/doc. This makes finding the POD for a specific macro easier.