| Server IP : 62.109.13.187 / Your IP : 216.73.216.11 [ Web Server : Apache/2.4.6 (CentOS) mpm-itk/2.4.7-04 OpenSSL/1.0.2k-fips PHP/8.2.28 System : Linux robothost.ru 3.10.0-1160.119.1.el7.x86_64 #1 SMP Tue Jun 4 14:43:51 UTC 2024 x86_64 User : mosrembit ( 6064) PHP Version : 8.2.28 Disable Function : NONE Domains : 0 Domains MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : ON Directory : /usr/share/doc/perl-podlators-2.5.1/ |
Upload File : |
podlators To-Do List This is a somewhat random and unordered list of things I'd like to see fixed or improved, but which I've not yet had a chance to do. Patches for any of the following are very much welcome. * Suppress the URL for L<|> if the link is just the anchor part of the tag with mailto: added to the front. Also strip the mailto: part if there is no anchor text. * Add a test suite for the pod2man and pod2text driver programs. This will probably require restructuring them so that they can be loaded with require, since otherwise it's too difficult to figure out how to run them with Perl. * There should be some way to turn off all heuristics when people are using POD for some purpose other than Perl or some other programming language with similar needs. The hooks are there in the code but we need an interface to set or unset them. * The test suite is still fairly basic, and doesn't test all of the options to the various modules, the scripts, =over/=back, or the guesswork in Pod::Man. * Pod::Text::Termcap can leave underlining turned on across a newline, resulting in weird visual artifacts. Ideally, underlining should be turned off at the end of each line, if still on, and then turned back on at the start of the subsequent line. The following items require changes to the POD specification and are therefore of broader scope than just this code: * Introduce a new interior sequence for metasyntactic variables, probably M<>, and reserve I<> exclusively for emphasis. This resolves a significant ambiguity in the current POD specification in a way that would make the Pod::Text output much better. (Metasyntactic variables should be surrounded in angle brackets and emphasized text should be surrounded by asterisks.) * Introduce a new interior sequence for footnotes. There has been extensive discussion of this on pod-people@perl.org. One proposal is to use a new formatting code for footnotes, probably N<>, and just in-line the footnote as part of the interior sequence. This doesn't allow multi-paragraph footnotes, however, so a second proposal is to have the content of the N<> formatting code be a unique marker that matches an =item tag in a new =begin footnotes section processed by translators that know how to do footnotes. (The translator should probably number the footnotes and insert some sort of numerical marker into the text at the point of the footnote.) This would require translators to formatting languages that do something more interesting with footnotes to parse the entire document, extract the footnote section, and then stick the footnotes back into the main text at the point where they occur, however. There are some preliminary patches for Pod::Man and Pod::Text in NOTES. It's possible to do footnotes directly in *roff (it's section T4 of the troff paper), but that relies on header and footer triggers and for terminal display it's becoming common to suppress the headers and footers. For the purposes of Pod::Man, end notes are probably a better model and can be handled about the same way as they are for Pod::Text. The following ideas about guesswork and heuristics were all taken from a post by Tom Christiansen to pod-people@perl.org: * All of the following should be okay to use verbatim in any POD text and have the translator do something appropriate: FILEHANDLE PackageName $variable @variable %variable &function $var::iable @vari::able %variab::le &functio::n function() fun::ction() fun::ct::ion() manpage(3r) user@host.com http://somewhere.com/stuff/ ftp://somewhere.com/stuff/ Pod::Man and Pod::Text handle much of this already, but not all of it (and I've not checked to see exactly where they break). * Something in __ALLCAPS__ should be in code font but perhaps not small, and maybe some magic between the unders, as in \f(CW_\|_ALLCAPS_\|_\fP. (Pod::Man handles the spaces between the underbars, but not putting this into code font.) * The module version number should be included in the headers/footers where appropriate. That means that when processing a module, ideally one wants to pull out the module's $VERSION to use in the footer rather than Perl's version.