Well, you botched the link (Yet Another XS Tutorial), and you ignored my suggestion of AnnoCPAN :) doesn't body well :P

other boring thoughtis perl docs -- I am so sick of..., Re: facing problem in parsing xml (perlintro, perlquote) / Re^2: giving spaces (perlrebackslash)/perlrebackslash, Better perldoc on Windows

Also

Learn Perl in about 2 hours 30 minutes
chromatics free book Modern Perl a loose description of how experienced and effective Perl 5 programmers work....You can learn this too.
PLEAC - Programming Language Examples Alike Cookbook

Living documentation? I've seen it on the php site (and some others), it turns into an idiot-forum wasteland rather quickly (incoherent attempts at asking for help not realizing its not a forum, repeated for 100 comments, no cleanup, eventually culminating in 100 responses of "find a forum")... a lot like various wikis where they encourage discussion .... horrible medium for this sort of thing

Living documentation often has unstated or hidden purpose, so lots of lots of everyone mistakes the purpose of the section, so you end up having "comments" begging for everything: introduction to the language syntax, introduction to programming, introduction to computers, introduction to typing, introduction to simple english .... for every single function entry

Will you be considering alternative languages?

• Pod::PerldocJp - perldoc that also checks perldoc.jp
• POD2::ES - Documentación de Perl en español
• POD2::IT - Italian translation of Perl core documentation
• POD2-

My suggestion, since I assume you'll be doing your own AnnoCPAN clone, see how it does annotation approval -- basically moderation -- it'll save your project; maybe

Also, ditch the existing layout (perlfunc...), give each keyword , each option its own page/heading/linktarget

Also, ditch the pod? :)

Also, ditch the pod prose formatting ; i've read someone comment they like the dense/prosy format of some of the docs because it really forces them to think and commit this to memory ;; I disagree with this; Each function/operator/construct should tell you what the name is, what the arguments are, what the return values are (and in what contaxt) in a list like format, examples also, none of this "I turned this list into prose so that you can remember it and weep for the dead list it came from thats flatter than the floor it lies on"

Also, have a perl version introduced "field" or list item or whatever ... wxPPIxregexplain.pl has some ideas like that buried here

Also, have portability "section" or list item or whatever .... for example, open, on win32 for unicode filename support use Win32::Unicode::Native

Also, have a "community tip" section ... for example readdir is low level, consider using File::Find::Rule or Path::Tiny

Also, community voting? moderator voting? downvoting? You have to be able to trim the inevitable garbage somehow ... and is it important to readers which editor edited which part or which sentence... not sure I care who added which node like it is on AnnoCPAN now ... I guess makes sense for current versions of docs ... but real perldocs don't have that, and if you're starting from scratch ... :)

Also, every single one of these things should be directly linkable, no excuse for it not to be (this part is why you might reconsider pod format and do with html/xml only)

Also, same with anchors, and no anchor mangling, if the user sees "Some heading here" the anchor should be "Some heading here" not "Some-heading-here" or a number...

Also, perldoc is already so overloaded name, taintperldoc? 2perldoc? LogicalPerldoc? LivingPerldoc?

What are your actual goals? Besides its-alive?

Whatever your goals, sounds ambitious, best of luck

Greetings.

Thanks for putting so much into your reply. I had actually envisioned much, if not most of what you spoke of.
Specifically:

• Login/registration via valid email. won't require response, but will validate it's existence (there's a Module for that™)
• Moderation - possibly by way of Peer Review, or at least Moderator
• Re Sectioned - the pods are already separate, but might do well to be further broken down
• Separate version - versions for each Perl version (separate Windows version?)
• Convert to (X)HTML - Undecided
• Augmentation - via Forum. I wrote a Forum back in the early `90's, and re-wrote it recently, so as to hoist it into the 21st century.
• {...}

Regarding Augmentation via Forum; I've seen this done before by way of a Teaser (comment on this...). That was a link to a section in a Forum. Liked it, and hated it simultaneously. Hated it, as you had no prior knowledge whether the comment you wanted to make wasn't already made by someone before you. You also end up loosing your place in the Document for no reason. Because you find someone already said that. I think a Forum would be helpful. But would never do it that way.

As AnnoCPAN goes; I intend to insert the comments into the document(s). As opposed to placing them into the margin(s). I think that given the comments are intended to augment the current, and that (by some means) the comments have been QC'd. It makes the document overall, better.

I also see no reason that (should I choose to leave it in pod format) it couldn't be shipped with Perl itself. Or as a diff for installations that already exist. In fact, authors of the comments could be <cite>ed throughout the document, and listed at the bottom. Which is, of course what CITE means. ;P

I will elaborate further. But as I haven't yet finished my first cup of coffee, I've already taken too big a chance writing this much. :)

Thanks again, for having shared such an elaborate opinion on this. I really appreciated it.

--Chris

P.S. Did I really overlook your reference to AnnoCPAN? (apologies, if I did)

#!/usr/bin/perl -Tw
use Perl::Always or die;
my $perl_version = (5.12.5);
print $perl_version;

Or as a diff for installations that already exist

If I understand it right, perldoc already is in a git repository (together with perl itself). If you could automatically turn this into pushes, that would be the best way (I think).

For several postings here, both of my own and from others, I wish for a version controlled PerlMonks. Your annotation system would be another candidate for such an approach.

The Wiki concept simply will not work from my point of view however. Too much mediation required.

Having very briefly perused the AnnoCPAN mods, there does seem to be a pretty good start in place.

I am asking myself how I would use this...

Apparently the original author intended for there to be a centralized location for a large public db as well as a 'personal' one for ones own use and reference. I would be very interested in the second, and somewhat less interested in the first. I am certain one could find a large volume of pretty good knowledge from that public repository, but I am guessing the queries would be templated, dictated, or minimally flexible.

The local one however could be much more open, perhaps allowing one to simply write SQL directly against the DB.

I wonder if one could grab from the public server only those comments/notes for those modules which are installed locally?

What does one do if one is using 2 or 3 versions of Perl locally? A db for each lib of mods? There are a lot of ways one could go with this!

I can think of a lot of ways that this could be very useful to me, but it would depend on whether I have a clear understanding of the way a local comment/note repository did or did not interact with the larger/public/central one.

Fun stuff!

Greetings, wjw.

I unpacked it, and built it yesterday. I didn't actually install it into my systems repository. But simply built, and tested it. Then moved it into a relative folder to the web space, and gave it a try.
It didn't work as expected. There appears to be at least one issue with it's call to DBI

index.cgi: Use of uninitialized value in lc at /my/path/to/site_perl/D
+BI.pm line 196
# path above modified, for brevity
[download]

I didn't really look into it, and don't really want to address it here (should probably go to SOPW). But I'm guessing it might have something to do with it's age, and possible differences in DBI -- AnnoCPAN::DBI v my system' DBI. Just thought I'd throw out a heads-up, that's all.

I too, thought about using my local system' Perl for the notes. As to my plans for this implimentation; I had intended to simply dump many, if not all versions of Perl into the CPAN folder, off it's root -- this is the default setup for Modules.
It downloads the repository there. The nice thing is. If you don't download the repository. You simply dump the tar balls into the CPAN folder, and it'll work from/on those. I thought that was a definite plus.

Sadly. Due to the DBI issue. I can't comment regarding the database setups you commented on. :(

Thanks, wjw. For taking the time to respond, and your thoughts on it.

EDIT: occurred to me just now, AnnoCPAN, as it is, mustn't be sending lang/encoding. Which causes DBI (and Perl) to complain.
Beginning to sound like a bit more work. :(

--Chris

#!/usr/bin/perl -Tw
use Perl::Always or die;
my $perl_version = (5.12.5);
print $perl_version;

You don’t have to worry about “writing too much.” as in fearing any sort of repercussions for merely discussing an idea.   What I’d like to know is, “how is this fundamentally different from a Wiki ... or, for that matter, from what PerlMonks (in its own quirky way ...) very effectively provides?

I ask this question strictly for clarification:   “What is the value-added of your idea?   What is novel and different about it?”

Also:   “If you build it, they will spam it ...”

Thanks for your response, sundialsvc4.

Great questions. Let me try to address them...

Difference(s):

WIKI, I love the concept. I spent ~4 months experimenting with every Perl based WIKI ever built -- I even finished, and experimented with those that hadn't been completed.

My findings;
* They're nearly impossible to control in a meaningful way (direct).
* They have no flow -- no logical sense of flow/direction. In fact, I found it easy to become lost in many of them, and make no mistake; I have an excellent sense of direction. :) In fact, the only WIKI that I ever found that had any semblance of logical flow, was docuwiki. But, of course, it's not Perl, and it's only logical in the sense that it uses categorization buckets.
* Don't even get me started on security/moderation. :)
In retrospect, I probably shouldn't have coined the term "living" in the Title of this. Given it's tight association with WIKI. But then again, maybe this will become what WIKI should have been. :)

What's different? ...
If I had to summarize; I'd probably say; logical flow, and categorization.
The Perl Documentation is already categorized. Flow, in the sense that everyone comments on sections that are meaningful to them, in those sections, and the comments flow in a meaningful way. Which also incites meaningful debate; maybe within the document, or re-derected to Forum (haven't concluded yet).

"... or, for that matter, from what PerlMonks (in its own quirky way ...)"
I have volumes to say on this topic, and well intend to do so. But to do it any justice. I want to create it's own topic. :)

“If you build it, they will spam it ...”
I'm guessing you have chosen not to have an email address because of this. :)

Thanks again, for taking the time to respond, sundialsvc4.
I hope I was able to address your questions adequately.

--Chris

#!/usr/bin/perl -Tw
use Perl::Always or die;
my $perl_version = (5.12.5);
print $perl_version;