The wiki (http://webwork.maa.org/wiki/HtmlLinks) mentions 3 topics (interval notation, syntax, units) available for display by the built-in helpLink. I have searched for the source of the helpLink subroutine in order to discover whether other topics might be displayed by it. I've found neither a path to the source code for helpLink nor a revised list of available topics (plus syntax and the key phrases to use when invoking helpLink).
The code for AnswerFormatHelp.pl invokes helpLink at various places and its distribution includes 15 "Entering-*.html" files (thanks Paul). Is there a style guide for writing additional help files to be used by either helpLink or AnswerFormatHelp? Can each tool use files written for the other?
Hi Dick,
helpLink() is defined in pg/macros/PGbasicmacros.pl
A quick look and it looks to me like helpLink() is indeed restricted to the three topics listed, and that Paul's AnswerFormatHelp.pl uses htmlLink() which has more flexibility.
The comments in PGbasicmacros.pl even admit that htmlLink() "needs refinement". I'd say feel free to make it better.
It looks to me like there is no particular style guide, the helpfiles just have to be valid html files.
It might be nice to have a style guide and an easy way to add custom help files.
Jason
helpLink() is defined in pg/macros/PGbasicmacros.pl
A quick look and it looks to me like helpLink() is indeed restricted to the three topics listed, and that Paul's AnswerFormatHelp.pl uses htmlLink() which has more flexibility.
The comments in PGbasicmacros.pl even admit that htmlLink() "needs refinement". I'd say feel free to make it better.
It looks to me like there is no particular style guide, the helpfiles just have to be valid html files.
It might be nice to have a style guide and an easy way to add custom help files.
Jason
Thanks, Jason, for the path. In hindsight, I suspect I used "fgrep helplink *.pl" rather than "fgrep helpLink *.pl" (i.e., "link" instead of "Link" [and not using the "-i" option for fgrep]) when I looked there.
I may experiment with its code by putting a modified version into my PGcourse.pl file (and perhaps also adding a line to course.conf).
I may experiment with its code by putting a modified version into my PGcourse.pl file (and perhaps also adding a line to course.conf).
John Jones commented on this also:
"One last thing on -- in looking for documentation I ran across the release notes for 2.4.9 and noticed AnswerFormatHelp. That should probably be merged with helpLink which is already in webwork -- they seem to be doing pretty much the same thing. In fact, the help they give for entering intervals is the same."
I haven't had a chance to look at the code closely but I agree in principle with John that we should merge these two -- it will be easier to maintain. helpLink is something which I believe I wrote for WW1, Paul Pearson wrote AnswerFormatHelp fairly recently. My suggestion is that we adopt Paul Pearson's AnswerFormatHelp, it's newer and has better formatting, and point helpLink() to it so that is still around for backward compatibility.
Does anyone see a downside to this? Are there things that helpLink does that AnswerFormatHelp doesn't? Is there a reason to merge in the other direction?
If you have time and energy to look into this Dick please go ahead. Feel free to combine them and/or improve on them both if you see how that can be done.
-- Mike
"One last thing on -- in looking for documentation I ran across the release notes for 2.4.9 and noticed AnswerFormatHelp. That should probably be merged with helpLink which is already in webwork -- they seem to be doing pretty much the same thing. In fact, the help they give for entering intervals is the same."
I haven't had a chance to look at the code closely but I agree in principle with John that we should merge these two -- it will be easier to maintain. helpLink is something which I believe I wrote for WW1, Paul Pearson wrote AnswerFormatHelp fairly recently. My suggestion is that we adopt Paul Pearson's AnswerFormatHelp, it's newer and has better formatting, and point helpLink() to it so that is still around for backward compatibility.
Does anyone see a downside to this? Are there things that helpLink does that AnswerFormatHelp doesn't? Is there a reason to merge in the other direction?
If you have time and energy to look into this Dick please go ahead. Feel free to combine them and/or improve on them both if you see how that can be done.
-- Mike
Was there any progress on this issue? Should AnswerFormatHelp or helpLink be used in new problems?
AnswerFormatHelp() is widely used and provides more types of help pages than helpLink(). I would suggest using the AnswerFormatHelp.pl macro in new problems.
That's my $0.02.
Paul Pearson