| Subject: | document how to do '## no extract maketext' in POD |
Based on:
http://perldoc.perl.org/perlpod.html
http://perldoc.perl.org/perlpodspec.html
http://docstore.mik.ua/orelly/perl3/prog/ch26_01.htm
I think we should go with the “null (zero-effect) formatting code”, Z<>, (i.e. Z<## no extract maketext>) because:
1. It is “A zero-width character” (i.e. it is not displayed) that “is nice for putting in front of sequences that might confuse something”. I’d call “## no extract maketext (for POD)” a sequence that might be confusing :)
2. The only caveat is that “it should have no content” so “a processor may complain” but regardless the “text should ignored” (i.e. it is not displayed).
3. But being able to hide the notation in rendered docs far outweighs a possible warning during rendering and its much less of a stretch than misusing the indexing code (X<>) to achieve the same results.
4. If POD ever has a proper inline-comment format we can change to that w/ a quick perl pie ;)