You are viewing a plain text version of this content. The canonical link for it is here.
Posted to modperl@perl.apache.org by Stas Bekman <st...@stason.org> on 2000/08/04 14:08:48 UTC
[doc writing] (was Re: Feature sets [was Re: Templating System])
On Fri, 4 Aug 2000, Matt Sergeant wrote:
> On Fri, 4 Aug 2000, Stas Bekman wrote:
>
> > > > > I hope that you write the doc is POD :)
> > > >
> > > > I suppose I could... I was planning on having a nice checklist of
> > > > features/systems that would be a pain to do in a fixed width font. An
> > > > HTML table would make my life MUCH easier there. Is there something in
> > > > POD that makes tables easier?
> > >
> > > Write the text in POD, and put the checklist data in with some neutral
> > > format. Then we can use a customized pod2html converter on it to generate
> > > a pretty table. XML would be a nice way to store the raw data. This
> > > might end up being kind of big for an in-line, so we could do something
> > > like "=table data_file.xml" and keep it in a separate file. (Or is it
> > > better to use "=for html" and put the rest inside that, so that it still
> > > passes syntax checks for standard POD?)
> >
> > I believe XML is a way too heavy for docs writing. Why one will want to
> > get a messy source code, when you can get away with a minimalistic POD.
> > Just look at the Guide's source code and look at the generated PDF --
> > isn't it great? I love POD. And if you want more than POD provides, it
> > takes secs to add the new functionality.
>
> People are migrating to XML because there are good editors coming onto the
> market (though sadly none for Linux yet, but I'm getting close to
> persuading Arbotext to port Adept to Linux...). The editors hide the
> complexity and you never need to see the source code. But its there if you
> need it (unlike Word, for example).
Well, this is a whole different story :) Once there will be such an
editor, things will be much better.
But you forget about the benefits of the source code editing, which is
diff and tools working with it. Surely enough big editors support their
own diff formats and tools, but they aren't possessed by many people. And
with POD everybody has a text editor :)
> > As for POD, I've already extended the POD in POD2HTML (which was buggy
> > anyway). For example, I've added new directives for embedding images,
> > linking to files and more... I don't afraid to extend the POD since I can
> > easily convert all my extended pod files back into the standard POD
> > format. So if you want a syntax for tables, this should be easy to add,
> > like:
> >
> > =table args
> >
> > =tr args
> >
> > =td args
> >
> > ...
> >
> > =/td
> >
> > =/tr
> >
> > =/table
Well, it was just an idea. It can be implemented in any other way...
> Ugh... I believe SDF has better support for tables, without resorting to
> nastiness like that. I think if you like POD, you'll love SDF, Stas.
>
> http://www.mincom.com/mtr/sdf/
Thanks for the link, Matt. I've seen this technology a while ago. The
reason that I didn't use it, is that it's a much bigger superset of syntax
that I need. If all I miss is a tables formatting, I'd rather add this
support than go for a complete format change.
Other than that, SDF looks really cool, and if you need more features
than provided by POD go for it. Especially cool thing, is that it provides
tools to convert to and from POD.
_____________________________________________________________________
Stas Bekman JAm_pH -- Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide http://perl.apache.org/guide
mailto:stas@stason.org http://perl.org http://stason.org/TULARC
http://singlesheaven.com http://perlmonth.com http://sourcegarden.org
Re: [doc writing] (was Re: Feature sets [was Re: Templating System])
Posted by Stas Bekman <st...@stason.org>.
> > But you forget about the benefits of the source code editing, which is
> > diff and tools working with it. Surely enough big editors support their
> > own diff formats and tools, but they aren't possessed by many people. And
> > with POD everybody has a text editor :)
>
> As with XML :)
But XML tends to look like HTML which is quite noisy.
> > > Ugh... I believe SDF has better support for tables, without resorting to
> > > nastiness like that. I think if you like POD, you'll love SDF, Stas.
> > >
> > > http://www.mincom.com/mtr/sdf/
> >
> > Thanks for the link, Matt. I've seen this technology a while ago. The
> > reason that I didn't use it, is that it's a much bigger superset of syntax
> > that I need. If all I miss is a tables formatting, I'd rather add this
> > support than go for a complete format change.
>
> I wonder if it would be easy to rip the table support out of SDF and use
> that, rather than change completely to SDF. I find table support to be
> POD's only real severe weakness.
Sounds like a good idea. I don't know what's the status of POD under
perl5.6 and what are the plans. I think TomC is still in charge of this
module.
_____________________________________________________________________
Stas Bekman JAm_pH -- Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide http://perl.apache.org/guide
mailto:stas@stason.org http://perl.org http://stason.org/TULARC
http://singlesheaven.com http://perlmonth.com http://sourcegarden.org
Re: [doc writing] (was Re: Feature sets [was Re: Templating System])
Posted by Matt Sergeant <ma...@sergeant.org>.
On Fri, 4 Aug 2000, Stas Bekman wrote:
> > People are migrating to XML because there are good editors coming onto the
> > market (though sadly none for Linux yet, but I'm getting close to
> > persuading Arbotext to port Adept to Linux...). The editors hide the
> > complexity and you never need to see the source code. But its there if you
> > need it (unlike Word, for example).
>
> Well, this is a whole different story :) Once there will be such an
> editor, things will be much better.
Well the tools are now pretty nice for Windows.
> But you forget about the benefits of the source code editing, which is
> diff and tools working with it. Surely enough big editors support their
> own diff formats and tools, but they aren't possessed by many people. And
> with POD everybody has a text editor :)
As with XML :)
> > Ugh... I believe SDF has better support for tables, without resorting to
> > nastiness like that. I think if you like POD, you'll love SDF, Stas.
> >
> > http://www.mincom.com/mtr/sdf/
>
> Thanks for the link, Matt. I've seen this technology a while ago. The
> reason that I didn't use it, is that it's a much bigger superset of syntax
> that I need. If all I miss is a tables formatting, I'd rather add this
> support than go for a complete format change.
I wonder if it would be easy to rip the table support out of SDF and use
that, rather than change completely to SDF. I find table support to be
POD's only real severe weakness.
--
<Matt/>
Fastnet Software Ltd. High Performance Web Specialists
Providing mod_perl, XML, Sybase and Oracle solutions
Email for training and consultancy availability.
http://sergeant.org | AxKit: http://axkit.org