Beefy Boxes and Bandwidth Generously Provided by pair Networks
"be consistent"
 
PerlMonks  

comment on

( [id://3333]=superdoc: print w/replies, xml ) Need Help??
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.


In reply to Re^2: Perl6 Pod -- reinventing the wheel? by j3
in thread Perl6 Pod -- reinventing the wheel? by j3

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others having a coffee break in the Monastery: (4)
As of 2024-03-19 10:22 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found