Fix invalid L<...> usage in POD.
#864
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
With this change the current pod parsing script will still work. Without this change the updated pod parsing script that is coming will not work, because the incorrect parsing that is currently being done for this invalid links is going to be removed. The most prevalent invalid `L<...>` usage comes in the form of `L<macros/macroName.pl>`. Following the correct usage rules this means a link to the header "macroName.pl" in the "macros" package. Clearly that is not correct. See https://perldoc.perl.org/perlpod#L-a-hyperlink for the `L<...>` usage rules. The updated script will honor those rules with the additional rules for local files that fit into that scheme: * For a link to a PG module, use the package name (exactly as the rules for `L<...>` dictate). * For a link to a `.pod` file, just use the basename without the `.pod` extension. So for example for a link to doc/MathObjects/UsingMathObjects.pod, use L<UsingMathObjects>. (See below) * For a link to a macro file (or script), use the basename of the macro file with the `.pl` extension and no path. This is actually how it already is in most files, except those fixed here. This also fixes the `L<MathObjects>` links. Those don't currently work, and won't start to work with the updated script. There is no `MathObjects` module or pod file. (There is a MathObjects.pl file, but that doesn't have good POD.) So this changes those to go to the `doc/MathObjects/UsingMathObjects.pod` file.
Alex-Jordan
reviewed
Jun 27, 2023
|
|
||
| L<macros/quickMatrixEntry.pl> | ||
| quickMatrixEntry.pl |
There was a problem hiding this comment.
Is this one supposed to have the L<...>?
There was a problem hiding this comment.
That macro does not have POD. So there is nothing to link to in the generated POD files. So no.
Alex-Jordan
approved these changes
Jun 27, 2023
|
Oops. I was wrong in my statement that this will work with the existing script. The macro links still work, but the module links don't. Open the link |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
With this change the current pod parsing script will still work. Without this change the updated pod parsing script in openwebwork/webwork2#2083 will not correctly resolve these links, because the incorrect parsing that is currently being done for these invalid links is removed.
The most prevalent invalid
L<...>usage comes in the form ofL<macros/macroName.pl>. Following the correct usage rules this means a link to the header "macroName.pl" in the "macros" package. Clearly that is not correct.See https://perldoc.perl.org/perlpod#L-a-hyperlink for the
L<...>usage rules. The updated script will honor those rules with the additional rules for local files that fit into that scheme:L<...>dictate)..podfile, just use the basename without the.podextension. So for example for a link to doc/MathObjects/UsingMathObjects.pod, use L. (See below).plextension and no path. This is actually how it already is in most files, except those fixed here.This also fixes the
L<MathObjects>links. Those don't currently work, and won't start to work with the updated script. There is noMathObjectsmodule or pod file. (There is a MathObjects.pl file, but that doesn't have good POD.) So this changes those to go to thedoc/MathObjects/UsingMathObjects.podfile.