Beefy Boxes and Bandwidth Generously Provided by pair Networks
Think about Loose Coupling
 
PerlMonks  

Re: Perl 6 Pod -- reinventing the wheel?

by chromatic (Archbishop)
on Nov 25, 2006 at 01:35 UTC ( [id://585955]=note: print w/replies, xml ) Need Help??


in reply to Perl6 Pod -- reinventing the wheel?

So, why is this particular wheel being reinvented?

There's already a perfectly good documentation format for Perl that has a much less bletcherous syntax. It's POD.

Now POD has its flaws, as anyone who's ever written a book in it will argue (and several of the people who've done so are actually on the Perl 6 design team), but it's also fairly nice in what it does include and how it does it.

More than that, whatever the document format of Perl 6, it must be portable to all of the systems where Perl 6 runs (and saying "every flavor of GNU/Linux that I've come across" doesn't really impress me with portability). It must be lightweight enough that it can be part of the core distribution. It should be sufficiently advanced over POD in Perl 5 to make up for any differences in syntax. It should fix as many of the warts of POD in Perl 5 as possible. It ought to be similar to POD in Perl 5 where possible, as change for the sake of arbitrary change is a lousy design goal. It needs to be extensible, which is one of the main problems of POD in Perl 5, and it should allow better reuse and introspection and customization than Perl 5's POD.

It's also very nice to control the document formatter used for the core documentation rather than relying on upstream to review patches and release new versions.

Replies are listed 'Best First'.
Re^2: Perl6 Pod -- reinventing the wheel?
by j3 (Friar) on Nov 25, 2006 at 02:37 UTC
    There's already a perfectly good documentation format for Perl that has a much less bletcherous syntax. It's POD.

    Actually, the syntax doesn't look bad to me. In comparison to POD, you've got @foo{bar} instead of F<bar>. On average, they both seem to take up about the same amount of space on the page too.

    Now POD has its flaws, {snip}, but it's also fairly nice in what it does include and how it does it.

    Yup. Texinfo seems ok too though. From the few times I've used it anyway.

    More than that, whatever the document format of Perl 6, it must be portable to all of the systems where Perl 6 runs (and saying "every flavor of GNU/Linux that I've come across" doesn't really impress me with portability).

    Which flavors of GNU/Linux *isn't* Texinfo available for? ;) Seriously though, since you can easily convert Texinfo to various formats (ex. HTML), MS Windows users should be able to access their docs just fine.

    It must be lightweight enough that it can be part of the core distribution.

    The only heavy part of Texinfo is TeX, which, of course, isn't necessary unless you want to produce dvi or pdf. Dunno how Texinfo-sans-TeX weighs in compared to the POD suite of tools, but I'm guessing the difference is not a big deal either way.

    It should be sufficiently advanced over POD in Perl 5 to make up for any differences in syntax.

    Check.

    It should fix as many of the warts of POD in Perl 5 as possible.

    Check.

    It ought to be similar to POD in Perl 5 where possible, as change for the sake of arbitrary change is a lousy design goal.

    Well, it's not arbitrary, since -- evidently -- there's reasons to go from Perl5's POD to Perl6's Pod. Perl5's POD is well-defined, and so is Texinfo, so a translator shouldn't be too much of a problem.

    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?

    and it should allow better reuse and introspection and customization than Perl 5's POD.

    Ah. Well, you've got me there. I think Ruby's doc system has some introspection built into it. That seems to come with its own problems though. For example, you re-open and extend a class but the docs either don't show your additions, or else you can no longer read the docs how they were before your addition (though I guess these are problems that can be worked through...).

    It's also very nice to control the document formatter {snip}

    Yes. I think this is a substantial tradeoff you make when using a standardized doc system outside of your own mothership. You get benefits too though, and I still think the idea has merit.

      What's not bletcherous about the # @directive syntax, especially after you add some mechanism of escaping that perl the compiler knows how to ignore but doesn't also turn normal commented-out code into formatting directives?

      What exactly is portable about "it runs on Linux and Windows users can just use HTML"? Do you know on how many other platforms Perl can run? You don't know how big the Texinfo distribution is, so I assume you likewise have no informed idea about the platforms it supports! How can you possibly argue that it's anywhere nearly portable enough to be part of the Perl 6 core without knowing at least these two important facts?

      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?

      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?

      Is Texinfo seriously an order of magnitude better than the POD 6 proposal? That's my threshold for such a large change. You have to address my four objections in a seriously impressive fashion to get my vote.

        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.

      and it should allow better reuse and introspection and customization than Perl 5's POD.
      Ah. Well, you've got me there.

      Hm. I just had another look at that S26.pod6, and I don't see anything about introspection. Is Perl6's Pod going to have special "smart" features like Ruby's? (which I'm none too crazy about anyway).

      Also, I don't know why this post got down-voted. I'm not trying to convince anyone to shoehorn-in Texinfo instead of Perl6's Pod. However, it sure seems like a whole extra boatload of work to change all the existing POD tools (and/or write new ones) when you could just grab an existing standard that has mature and debugged tools ready and waiting. {shrug}

      Is there some stigma against Texinfo that I'm unaware of?

Re^2: Perl 6 Pod -- reinventing the wheel?
by blazar (Canon) on Nov 25, 2006 at 21:20 UTC

    There's already a perfectly good documentation format for Perl that has a much less bletcherous syntax. It's POD.

    Now POD has its flaws, as anyone who's ever written a book in it will argue (and several of the people who've done so are actually on the Perl 6 design team), but it's also fairly nice in what it does include and how it does it.

    Hmmm, it seems I've mentioned YAML quite often lately. (Although I'm not really sure whether two entries count as "quite often" even if so close in time.) Now, it may seem OT to mention it in this thread too. But your points gave me the chance to expose a meditation that's been in my head for some time now. Now, both YAML and POD are LWMLs. As it happens, LWMLs are typically divided in two categories of which each of them is part respectively: namely, data serialization oriented and presentation oriented ones.

    XML, for example, is suitable both for presentation and data serialization. But it sure is not lightweight. Now, I'm not really asking about merging (something based on) POD with (something based on) YAML. But I'd be interested in the feasability of an actual lightweight markup that could be suitable both for presentation and for data serialization. A first remark that one may make is that there are good reasons to keep logically different things, ehm, different. But it's also true that document description involves very similar issues to those that one can find in data serialization, e.g. wrt sectional divisions or special lists and many other things. So solving the problem once may be enough. Solving it in a way that is both forgiving enough for one task, and precise enough for the other IMHO would mean to achieve flexibility and reliability. Provided that it's possible, but then that's why I'm asking here...

Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others making s'mores by the fire in the courtyard of the Monastery: (4)
As of 2024-03-19 10:44 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found