Re: Perl Module Documentation

Replies are listed 'Best First'.
Re^2: Perl Module Documentation by BrowserUk (Patriarch) on Dec 20, 2011 at 19:32 UTC
Via /msg: ww says Re Re^2: Perl Module Documentation -d -T -o and note carefully that I said "starting point" -- NOT, here's a script to do the conversion Those options certainly did not stand out to me as a mechanism by which the OPs question could be solved. And even now you pointed them out I still wouldn't have a clue how to use them to solve his problem. Perhaps you would consider supplying a little more info on how to go about it? I asked because I would very much like to know how to do this. I have and use daily, minute by minute, the AS HTML treeview built by AS. But: it only includes modules installed by PPM, not those I build/install via other mechanisms; it includes POD for a whole bunch of stuff from the AS & standard distribution that I'm not interested in and would like to exclude. Eg. I Have no use for this lot: Getting Started Welcome To ActivePerl Release Notes Installation Guide Getting Started ActivePerl Change Log More Resources License and Copyright ActivePerl Components Overview Using PPM Windows Specific OLE Browser PerlScript PerlScript Examples PerlEz Perl for ISAPI ActivePerl FAQ Introduction Availability & Install Docs & Support Windows Specific FAQ Perl for ISAPI Windows 9X/Me/NT/200X/XP Windows Quirks Web Server Configuration Web Programming Windows Programming Modules & Samples Embedding & Extending Using OLE with Perl Windows Scripting Active Server Pages Windows Script Host Windows Script Components [download] Or this junk: <Reveal this spoiler or all spoilers in this node or all in this thread> Or this stuff: perlbook perlcommunity perltodo perldoc perlhist perldelta perl5101delta perl5100delta perl595delta perl594delta perl593delta perl592delta perl591delta perl590delta perl589delta perl588delta perl587delta perl586delta perl585delta perl584delta perl583delta perl582delta perl581delta perl58delta perl573delta perl572delta perl571delta perl570delta perl561delta perl56delta perl5005delta perl5004delta perlartistic perlgpl perlcn perljp perlko perltw perlaix perlamiga perlapollo perlbeos perlbs2000 perlce perlcygwin perldgux perldos perlepoc perlfreebsd perlhaiku perlhpux perlhurd perlirix perllinux perlmachten perlmacos perlmacosx perlmint perlmpeix perlnetware perlopenbsd perlos2 perlos390 perlos400 perlplan9 perlqnx perlriscos perlsolaris perlsymbian perltru64 perluts perlvmesa perlvms perlvos [download] and it includes whole heaps of stuff from some modules that I would like to exclude. Eg. This junk from Date::Manip <Reveal this spoiler> And this from somewhat similar crap from DateTime : <Reveal this spoiler> And there's more. Much, much more! I can manually trim these out, but the next time I install a module with PPM, it rebuilds it all and everything reappears. I would really like to find a way to produce an HTML doc stack of just the bits of POD that I find useful. So you see. My question was not an idle one, but actually an attempt to illicit further info on how to go about this. The said. RTFM replies are only really useful if the information asked for is there and obvious and likely to be both recognised and understood by the OP. And despite the time I've been around Perl, your post did not help me answer the question. With the rise and rise of 'Social' network sites: 'Computers are making people easier to use everyday' Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error. "Science is about questioning the status quo. Questioning authority". In the absence of evidence, opinion is indistinguishable from prejudice. The start of some sanity?	[reply] [d/l] [select]
Re^3: Perl Module Documentation by ww (Archbishop) on Dec 20, 2011 at 20:45 UTC
Sorry; I thought you were gratuitously "bustin' my chops;" I see differently now and apologize for the deficiencies in my reply. They were numerous. The options I mentioned allow you to selectively produce a plain text file (formatted with spaces and newlines) of the relevant doc (and pod, TBOMK) using a CLI command like this (under Win): `F:\pl_docs>perldoc -d nextpod.out -T -o f next Perldoc (Pod::Perldoc::ToText) output saved to nextpod.out` [download] The -d argument is the outfile name; -T says "don't page" and -o can specify a format, but is not something I've played with seriously. (Note, NO hyphen before the "f" preceding the function name. I have no clue why it works that way.) From there, wrap the output in minimal html, `html <head> <title> <!-- (module or function title) --> </title> </head> <body> <pre> <!-- (content of your output from above, verbatim) --> </pre> </body> </html>` [download] However, automating the above in a script may be more work than I've considered. Making the .html 'semantic' would certainly be more work. So, in all honesty (/me flushes with pseudo-embarassment and pride at his self-congratulatory caveat), RichardK's pointer to Pod::Webserver now seems likely to be a far better way to do the job, unless it's bug-ridden. And in further honesty, you're right about needing to be obvious -- I just thought it would be to a Monk as experienced and wise (if sometimes, a tad sharp with others) as you. But since the post will stand for others, apologies, also, for failing to follow that guidance. But, afterthought, would you please stick <c>readmore<c>s in there somewhere?	[reply] [d/l] [select]
Re^4: Perl Module Documentation by BrowserUk (Patriarch) on Dec 20, 2011 at 21:03 UTC
But, afterthought, would you please stick `readmore`s in there somewhere? As all the long stuff is wrapped in `<spoiler>` tags, you should not be seeing any of it unless you explicitly click one of the links in: `<Reveal this spoiler or all spoilers in this node or all in this thread>`. Whereas, if I had used `<readmore>`'s, everyone would have to suffer it all as soon as they opened the post. With the rise and rise of 'Social' network sites: 'Computers are making people easier to use everyday' Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error. "Science is about questioning the status quo. Questioning authority". In the absence of evidence, opinion is indistinguishable from prejudice. The start of some sanity?	[reply] [d/l] [select]
Re^2: Perl Module Documentation by BrowserUk (Patriarch) on Dec 20, 2011 at 18:12 UTC
Does your perldoc help output show you options that mine doesn't? Cos I don't see anything there that suggests it converts installed module POD to an AS-style HTML treeview: c:\test>perldoc -h perldoc [options] PageName\|ModuleName\|ProgramName... perldoc [options] -f BuiltinFunction perldoc [options] -q FAQRegex perldoc [options] -v PerlVariable Options: -h Display this help message -V report version -r Recursive search (slow) -i Ignore case -t Display pod using pod2text instead of pod2man and nroff (-t is the default on win32 unless -n is specified) -u Display unformatted pod text -m Display module's file in its entirety -n Specify replacement for nroff -l Display the module's file name -F Arguments are file names, not modules -D Verbosely describe what's going on -T Send output to STDOUT without any pager -d output_filename_to_send_to -o output_format_name -M FormatterModuleNameToUse -w formatter_option:option_value -L translation_code Choose doc translation (if any) -X use index if present (looks for pod.idx at C:\Perl64\lib) -q Search the text of questions (not answers) in perlfaq[1-9] -f Search Perl built-in functions -v Search predefined Perl variables PageName\|ModuleName... is the name of a piece of documentation that you want to look + at. You may either give a descriptive name of the page (as in the cas +e of `perlfunc') the name of a module, either like `Term::Info' or + like `Term/Info', or the name of a program, like `perldoc'. BuiltinFunction is the name of a perl function. Will extract documentation f +rom `perlfunc'. FAQRegex is a regex. Will search perlfaq[1-9] for and extract any questions that match. Any switches in the PERLDOC environment variable will be used before t +he command line arguments. The optional pod index file contains a list o +f filenames, one per line. [Perldoc v3.15] [download] With the rise and rise of 'Social' network sites: 'Computers are making people easier to use everyday' Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error. "Science is about questioning the status quo. Questioning authority". In the absence of evidence, opinion is indistinguishable from prejudice. The start of some sanity?	[reply] [d/l]