Beefy Boxes and Bandwidth Generously Provided by pair Networks
good chemistry is complicated,
and a little bit messy -LW
 
PerlMonks  

ePod - write easy and simple in easy-POD, convert to POD, and from there you know the way.

by gmpassos (Priest)
on Jan 14, 2004 at 01:20 UTC ( [id://321154]=perlnews: print w/replies, xml ) Need Help??

I have just released the new module ePod.

To write the POD of my modules I was using a simpler way to write POD (that I call easy-POD or ePod), then for a documentation project I introduced this ePod, and the doctors where able to write their texts easy and fast whit it.

Soo, I turned this into a module and published it to the public:
http://cpan.org/authors/id/G/GM/GMPASSOS/ePod-0.01.tar.gz

ePod syntax is very simple and intuitive, that I just need to show an example that you get it (specially if you know POD):

=> Tutorial Sampler text bla bla bla bla ==> Sub topic X X is before Y. ==> Sub topic Y Y is before Z. *> A text of the item A. **> A.1 ***> A.1.1 **> A.2 => Author Foo <foo at mail.foo>
But the POD syntax is compatible with ePod, soo you still can use I<>, B<>. L<> and C<> formaters, the =include command, and VERBATIN data:
=> Break Math Some simple Math: ## A simple definition: A = B ## Now multiply both side by A: A**2 = AB ## Now add A**2 - 2AB in both sides: A**2 + A**2 - 2AB = AB + A**2 - 2AB ## That we can simplify by: 2(A**2 -AB) = A**2 - AB ## And finally we divide both sides by A**2 - AB: 2 = 1 Soo, 2 is really equal 1? But we didn't anything wrong! Hummm, take a deep look! Som link sample: L<X|http://somedomain>
But the best thing of ePod is to use it to fix things that you generally make in POD, soo this is a valid syntax:
=> Don't worry about lines and spaces! We can write everything grouped. *> including itens and their texts! ==> And now we know why POD need the spaces, since we can see how the text looks ugly in this way.

Well, I hope that this can be useful for others. Enjoy! ;-P

Graciliano M. P.
"Creativity is the expression of the liberty".

Replies are listed 'Best First'.
Re: ePod
by markov (Scribe) on Jan 14, 2004 at 10:36 UTC

    Did you take a look at OODoc? It provides an extendible syntax, based on plain POD, with logical markup. It can produce real POD and nice HTML.

    You can even add your own parser to OODoc, to parse the syntax of ePOD, and use the output formatters provided by OODoc. That way, you can focus more on the features you provide and less on the output you have to produce.

    See http://perl.overmeer.net/oodoc/ for examples and documentation.

Re: ePod - write easy and simple in easy-POD, convert to POD, and from there you know the way.
by Anonymous Monk on Jan 14, 2004 at 11:16 UTC
    Why should I use this? What advantage does it have over POD? As it is, POD has a very simple syntax, is easy to use and already has a plethora of tools available for it's manipulation and output. Why should I bother with "yet another replacement for a problem that doesn't exist"?
      Well, this was instroduced to fix this problem: "How to enable non-programmer peoples, non geeks, to write docs easy and fast, and have this docs in a structured and indexed database".

      Well, the near solution was POD, but don't forget that they are non-programmers, soo they won't take care to write right a syntax, they will just write! Soo, how to let them to write and be able to fix their errors? And making this fixer borns ePod.

      As I said, I have tested this with docstor, that don't know and don't want to know about syntax, nad don't have time. And the result was perfect. They don't know how they just write fast a doc, that can be written even in their Palm, and have nice well formated documents in the site, including full indexed search. The best thing is that no one needed a course about "how to write the docs", they just write and post to the site.

      I know that this can be very simple and POD is simple, but have a try! Any way, it's here for any one.

      Graciliano M. P.
      "Creativity is the expression of the liberty".

        As I said, I have tested this with docstor, that don't know and don't want to know about syntax, nad don't have time. And the result was perfect ... The best thing is that no one needed a course about "how to write the docs", they just write and post to the site.

        I don't buy it - Instead of allowing the use of descriptive formatting delimiters such as =head and =item, you replace them with shorthand symbols. The use of shorthand cryptic symbols does nothing to make POD more usable to non-programmers - If anything, this makes it less accessible to non-programmers as there needs to be an association made, which may not always be obvious, between the symbol and it's context and meaning.

        If you really wanted to create a tool for non-programmers to create POD, why not create a word processor which allows for a WYSIWYG interface whilst outputting validate POD. Instead, all that you have done is create a cryptic shorthand to replace formatting directives which are already self-explanatory and straightforward.

        A better name for this module might be POD::Shorthand or POD::Cryptic, but certainly not anything which suggests that this format is "easy" compared to POD.

Re: ePod - write easy and simple in easy-POD, convert to POD, and from there you know the way.
by gmpassos (Priest) on Jan 14, 2004 at 14:37 UTC
    Thanks for the tip. But the idea of ePod is to always convert it to POD, and produce nice well formated POD. For example, this ePod:
    => Break Math Some simple Math: ## A simple definition: A = B ## Now multiply both side by A: A**2 = AB ## Now add A**2 - 2AB in both sides: A**2 + A**2 - 2AB = AB + A**2 - 2AB ## That we can simplify by: 2(A**2 -AB) = A**2 - AB ## And finally we divide both sides by A**2 - AB: 2 = 1 *> Soo, 2 is really equal 1? *> But we didn't anything wrong! *> Hummm, take a deep look! Som link sample: L<X|http://somedomain> => Font I<"The Last Theorem of Fermat".>
    Will generate this POD:
    =head1 Break Math Some simple Math: ## A simple definition: A = B ## Now multiply both side by A: A**2 = AB ## Now add A**2 - 2AB in both sides: A**2 + A**2 - 2AB = AB + A**2 - 2AB ## That we can simplify by: 2(A**2 -AB) = A**2 - AB ## And finally we divide both sides by A**2 - AB: 2 = 1 =over 10 =item Soo, 2 is really equal 1? =item But we didn't anything wrong! =item Hummm, take a deep look! Som link sample: L<X|http://somedomain> =back =head1 Font I<"The Last Theorem of Fermat".> =cut
    Soo, ePod is indirectly suported by OODoc.

    To generate the HTML files I use Pod::HtmlEasy

    What I think interesting on OODoc is the use of templates to generate the HTML. How they work?

    Graciliano M. P.
    "Creativity is the expression of the liberty".

      But the idea of ePod is to always convert it to POD, and produce nice well formated POD.

      There is not a big difference between "can produce POD" (and HTML) and "always produces POD". So why a "But"?

      What I think interesting on OODoc is the use of templates to generate the HTML. How they work?

      Just like CGI templates: have a constant template, which indicates where dynamic data must be filled in. You can best look at the examples included in the distribution. For HTML you may need a lot of templates, but for POD it is very very simple.

      In my experience, POD (being a visual markup language) does not contain sufficient information to create good HTML. The resulting HTML can be much nicer. See for instance the Mail::Box docs. For the author, it still looks like POD...

Log In?
Username:
Password:

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

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

    No recent polls found