Beefy Boxes and Bandwidth Generously Provided by pair Networks
Problems? Is your data what you think it is?
 
PerlMonks  

Re^4: Perl 6 Pod -- reinventing the wheel?

by j3 (Friar)
on Nov 25, 2006 at 04:12 UTC ( [id://585967]=note: print w/replies, xml ) Need Help??


in reply to Re^3: Perl 6 Pod -- reinventing the wheel?
in thread Perl6 Pod -- reinventing the wheel?

Hi chromatic. Listen, I'm not trying to sell Texinfo (though I do like it pretty well), and I haven't looked closely enough at Perl6's Pod to suggest whether or not I think it's better than some other format. My original post was asking if and why this wheel is being reinvented. Evidently it is, and the leaders of the Perl community think it is justified or else they wouldn't be using TheDamian's formidable skills to work on it. But I'm still curious about the "why".

What's not bletcherous about the # @directive syntax,

If you're used to Texinfo, POD looks kinda' ugly. Same thing vice versa. Eye of the beholder and all.

What exactly is portable about "it runs on Linux and Windows users can just use HTML"?

What's portable about it is, if there's some problem building makeinfo on your platform, you could always browse the docs as html (either in a GUI or text-based html browser).

You don't know how big the Texinfo distribution is, so I assume you likewise have no informed idea about the platforms it supports!

Well, this seems to be the latest version: texinfo-4.8a.tar.bz2    26-Sep-2006 18:39    1.5M

It's standard GNU fare (./configure; make; make install), so that means it'll likely build on most Unixy platforms (including Mac OS X). Dunno about MS Windows.

It needs to be extensible, which is one of the main problems of POD in Perl 5,
Dunno what you mean here. What do you need in a doc system that's not in Texinfo? And why would it be hard to extend Texinfo?
What exactly is easy to extend about Texinfo unless the Perl 6 maintainers fork their own version and add their own features, rather than relying on upstream to make those changes?

I'd suggest that if the Perl6 maintainers needed a feature, and submitted a patch that it might get accepted. But I see your point: that could certainly be a pain in the neck. Noted. In the end, you could be stuck writing your own makeinfo_pod6.pl.

How exactly is making everyone who wants to write POD in Perl 6 learn a completely new style of syntax with a new escaping system that POD has never needed before not an arbitrary change?

Perhaps the changes being made to POD are not as substantial as I'd assumed. From a casual user's perspective, it looks like this: Perl5's POD evidently needs sprucing up (i.e. to be more compact, uniform, and expressive). Joe-user says, "well, I use <formatting/markup system X> and it's fairly compact, uniform, and expressive -- why should I take the time to learn Perl6 Pod when I could just use X?".

So, on the one hand, yes, changing from Perl5's POD to something completely different would make a hoard of folks annoyed that they have to learn a different markup to write Perl6 docs. OTOH, some other subset of users would be relieved that they no longer have to use *2* different markups (POD *and* DocBook/LaTeX/Texinfo/doxygen/whatever) depending upon what they're documenting. I'm not suggesting that the 2nd subset is larger than the hoard though.

Is Texinfo seriously an order of magnitude better than the POD 6 proposal?

I doubt it. Though, as long as we're here, consider this:

  • What if you already know and use markup X (where, I'm thinking Texinfo here)? If Perl6 Pod became "just like X", now your productivity at creating docs all of a sudden just went up substantially.
  • If Perl6 Pod went X, now the developers who were going to be reworking Perl5's POD tools are now freed-up and can instead spend time hacking Perl6.
  • The Perl community would be doing its part to stave off the "Yet Another Doc Format" situation.

Anyway, those were just a few thoughts. I'm sure Perl6 Pod will be very nice, complete, and stable system that new users will learn and get used to when they take up Perl6. It would be nice, IMO, to instead use a system that's similar to an already-in-place standard that many folks already know, but I guess that describes Perl5's POD just as well as some of the other alternatives.

Replies are listed 'Best First'.
Re^5: Perl 6 Pod -- reinventing the wheel?
by chromatic (Archbishop) on Nov 25, 2006 at 05:51 UTC

    You didn't respond to what I consider the two most important reasons why Texinfo is a poor fit.

    I'm curious to see your proposal for (what I believe will be a non-standard) escaping syntax so that comments that include Perl arrays don't accidentally turn into Texinfo directives.

    Also, I stand by my assertion that any "solution" that doesn't allow people on any platform other than GNU/Linux to produce documents is completely unacceptable.

    What if you already know and use markup X (where, I'm thinking Texinfo here)? If Perl6 Pod became "just like X", now your productivity at creating docs all of a sudden just went up substantially.

    What if all of the existing Perl users have already encountered POD in its current form? Again, one of the major principles of the Perl 6 redesign is "Don't change things arbitrarily. Changes require compelling justifications of cleanliness, simplicity, discoverability, and consistency."

    If Perl6 Pod went X, now the developers who were going to be reworking Perl5's POD tools are now freed-up and can instead spend time hacking Perl6.

    Damian volunteered to revise POD for Perl 6. As I said before, at least three members of the Perl 6 design team have written more than one book in POD. We believe it is a solid system.

    As a side note, be very careful about even intimating that you can tell a volunteer developer what he or she should work on.

    The Perl community would be doing its part to stave off the "Yet Another Doc Format" situation.

    As you admit, POD already exists.

    So again, with licensing problems, syntax problems, and the arbitrariness of such a dramatic change in the face of little benefit (and contra the previous two problems), what exactly again is the benefit?

    Also, what in the world do you mean by "reinventing the wheel"?

    Also, I've tried to use info many times and found that it never lived up to its name.

    (Also, it's "Perl 6".)

    Update: reworded.

      Sorry -- this thread seems to be blowing way out of proportion. I may have unintentionally hit a nerve.
      I am still waiting for your explanation of the escaping syntax so that comments that include Perl arrays don't accidentally turn into Texinfo directives.

      Oh. I don't think I understand what you're talking about. In that Texinfo example I was using in the OP, I figured:

      # This is a regular comment. Don't start one of # these with a '#@'. #@ This could be a Pod comment. #@ Make sure they always start with a '#@'.
      I am still waiting for you to realize that any "solution" that doesn't allow people on any platform other than GNU/Linux to produce documents is completely unacceptable.

      Last time I used MS Windows I either used ActivePerl and read the local docs with Firefox, or else installed Cygwin and read them using perldoc in a bash shell. I guess if you need docs accessible in some sort on MS Windows shell, and if makeinfo can't be made available for that environment, then GNU's makeinfo is out.

      Why did you ignore those two points in your response? They are of supreme importance!

      Sorry -- didn't mean to ignore them.

      What if you already know and use markup X (where, I'm thinking Texinfo here)? If Perl6 Pod became "just like X", now your productivity at creating docs all of a sudden just went up substantially.
      What if all of the existing Perl users already have encountered POD in its current form? Again, one of the major principles of the Perl 6 redesign is "Don't change things arbitrarily. Changes require compelling justifications of cleanliness, simplicity, discoverability, and consistency."

      Then their productivity writing docs stays the same I suppose. Look, I agreed that I don't think Texinfo is an order of magnitude better than Perl 6 Pod. I *do* think that Texinfo is fairly well-used and has tools already available. My comment you're replying to there is just additional considerations to think about: that is, even though Texinfo probably isn't 10 times better than Pod (your criteria), there are some less tangible benefits to it. That's all. Maybe those less-tangibles don't weigh very much here. Maybe they don't weigh much at all. That's what I was hoping to find out more about in my original post.

      Damian volunteered to revise POD for Perl 6.
      And we're all very grateful for it.
      We believe it is a solid system.

      Sweet. Recall, in the original post I asked about if Perl 6 Pod is reinventing the wheel and (assuming it was), why. I was not implying that Perl 6 Pod wasn't solid.

      As a side note, be very careful about even intimating that you can tell a volunteer developer what he or she should work on.

      I hope I haven't ever given that impression. It's certainly none of my business what itches folks choose to scratch. Neither is it any of my business to try and guide the path of any project that isn't my own. I can still be curious about why that path was chosen though.

      So again, with licensing problems, syntax problems, and the arbitrariness of such a dramatic change in the face of little benefit (and contra the previous two problems), what exactly again is the benefit?

      Seems like there's some benefits as well as drawbacks (outlined elsewhere in this post and others). I was asking if maybe it would be simpler to use a pre-existing doc system (like, for example, maybe Texinfo, since it came to mind while I was posting, and since I've used it before and it seemed pretty good for this type of use, and since it is GPL'd (like one of Perl's licenses) and the FSF uses it for all their software).

      Also, what in the world do you mean by "reinventing the wheel"?

      I meant this:

      1. Programming language project needs way to include docs in source.
      2. Perl 5 POD is created.
      3. Time passes.
      4. According to S26, "The Pod Dialect": "Compared to Perl 5 POD, Perldoc's Pod dialect is much more uniform, somewhat more compact, and considerably more expressive.". So it seems that the project was at some point in the recent past looking for a much more uniform, somewhat more compact, and considerably more expressive alternative to Perl 5 POD.
      5. This reader (yours truly) says to self, "Hey, I think there are already existing alternatives like that!".
      6. For various reasons, this reader assumes that Perl 6 Pod is substantially different than Perl 5 POD, and thinks the switch to Perl 6 Pod involves a rewrite and a lot of work.
      7. Rewriting when already-written/tested/mature alternatives are available looks like reinventing the wheel to the reader. Reader posts about it, but seems to inadvertantly ruffle some feathers.
      Also, I've tried to use info many times and found that it never lived up to its name.

      Personally, I tend to have to relearn it every time I touch it, but I figure that's just because I use man pages far more often (since they're much simpler to use). That said, I really like the DVI and PDF output generated from texi docs though. Also I like that you can put mathematics in your Texinfo docs.

      (Also, it's "Perl 6".)
      I've been using "Perl6" because I thought it would be easier to google for later on.
        I am still waiting for your explanation of the escaping syntax so that comments that include Perl arrays don't accidentally turn into Texinfo directives.
        Oh. I don't think I understand what you're talking about. In that Texinfo example I was using in the OP, I figured:
        # This is a regular comment. Don't start one of # these with a '#@'. #@ This could be a Pod comment. #@ Make sure they always start with a '#@'.

        chromatic isn't talking about this. How do you suggest to escape these so that texinfo parses them correctly?

        #@ @node do_something #@ #@ @array has to be defined. #@ #@ You'd use this @emph{awesome} function.. #@ #@ Also note that hash slices like @hash{oops} are needed. #@
Re^5: Perl 6 Pod -- reinventing the wheel?
by DrHyde (Prior) on Nov 27, 2006 at 10:35 UTC
    Ooh goodie, if there's a problem building texinfo on my machine I can read the docs in HTML. Of course, I'm fucked if I want to write my own documentation for my own code.

    Yes, texinfo itself might only be 1.5MB, but you seem to have forgotten to take into account its dependencies. Those which are required by texinfo and not by perl come to something like 50MB. Which is one reason that I generally don't bother with texinfo. 50MB is a *lot* of storage to dedicate to a documentation system.

    And finally, "It's standard GNU fare (./configure; make; make install), so that means it'll likely build on most Unixy platforms (including Mac OS X). Dunno about MS Windows" indicates not only a great deal of ignorance (GNU fare can be exceedingly hard to build on a great many UNIXy and non-UNIXy platforms (VMS, anyone?) due to incompatible extensions in GNU make and in the GNU shell which Linux-using idiots try to call /bin/sh when they shouldn't, and so on) but also a distressing lack of concern for a significant proportion of the user base.

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://585967]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others studying the Monastery: (4)
As of 2024-03-19 04:56 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found