On Fri, 22 Sep 2023 11:02:44 +0200
Mark Overmeer <[email protected]> wrote:
> Just as Dmitry Karasik experienced, I encountered blockades by core
> maintainers to even think about improvements...
<with my PSC hat on> Hi. I'm here.
> My biggest complaints:
> - Pod uses visual markup, like =item, where it should use
> semantic markup, like =sub
> - Pod does not support anything related to Object Oriented features,
> like documenting inheritance relationships
The formatting-verses-semantic issue is a large one, yes. I could
imagine a way to solve it somewhat similar to how HTML-vs-CSS does
things, or the manpage macros in nroff, or if you stare at it weirdly,
the Scheme r7rs-small vs r7rs-large difference.
That would be, that Pod itself would have two layers to it. There needs
to be a few extra bits and pieces of purely visual style (e.g. my
underline idea), but those seem relatively simple and uncontentious to
be added.
But next up, you'd want to define a big set of "semantic directives",
which could be expanded out by some sort of translation layer by
application of a template or somesuch, into being the visual layer
instead. Quite what form that expansion layer takes - whether it is a
piece of code somewhere, or a template file in some format - would need
further looking at. But the overall idea is that it solves the same
kind of problem as r7rs small-vs-large split: Document authors can
write using the full set of semantic directives if they wish, while
implementors only have to care about building the visual formatting
stuff, knowing that the templating translation bit in the middle will
do its thing.
Such a mechanism would need to be easily extensible of course. Whenever
I look at someone's attempt to define a list of what semantic things
they'd want to document I always find that list comes up short. Did you
think about events? Signals? Mutable accessors as separate from mere
method calls? Did you list the standard config file keys your class
looks at? Does your UI widget define its stylesheet parameter names and
default keybindings? The list goes on. The moment you start to let
people define semantic things as real entities aside from simply being
a formatted document of text, people will want to come up with their
own new categories of thing to write about. You must allow them to do
so.
> - Pod limits the quality of the manpage: support for more
> fine-grained links, for instance, could produce better HTML
> accessibility.
Yes; the existing L<> is a little disappointing in that respect.
> So, back in 2003, I developed OODoc (OpenOffice did not exist yet).
...
> Eh, but it's my 2003 view of the World. It needs some (mainly visual)
> cleanup.
Mmm; it seems somewhat similar to Pod6 there.
> > [...], than have to throw it all out and replace it with
> > something else entirely.
>
> The distance between what POD is, and what a convenient documentation
> syntax should be, is really big.
Perhaps, perhaps not. It depends how you look at it.
I'm coming at this from having written App::sdview ("Structured
Document Viewer"), which is intended as a nicer viewer for manpages and
similar. It reads nroff, POD, Markdown, renders to a terminal, and can
output in those formats plus also HTML. What I've found is that trying
to cross-convert between nroff/POD/Markdown is largely
straight-forward on the common overlap. The reason I want to add things
like underline and code fences with language names to POD is that those
are relatively small easy things it's missing from some of the others.
But largely it fills a similar goal doing similar things.
Certainly if you compare POD to something like Javadoc, the differences
become much greater. Javadoc is intended verymuch for attaching
documentation to language-specific things. Nobody would use Javadoc for
writing a generic document that was unattached to a specific piece of
code; whereas look at all the .pod files sitting around in core perl
source that are unattached to code - be it Perl or C code.
> Perl-Core developers have shown to refuse even small useful changes
> in the past.
>
> I wrote a first version of pod6 for Perl6, which Damian transformed
> into the existing pod for Raku. We may finally get an acceptable
> quality pod syntax in Perl5, if we integrate that Raku spec into
> Perl5. That might finally convince some Core developers to accept
> dire needed improvements.
Yes I've been reading the Pod6 docs, and there's a few bits I want to
steal - U<underline> and tables being two. But overall I still feel
it's trying to edge its way much more in the direction of e.g. Javadoc
and become something very tightly integrated to the surrounding Raku
code, and in doing so ends up forcing a lot more rigid structure on
authors. I ultimately don't know whether that is a good thing or not.
--
Paul "LeoNerd" Evans
[email protected] | https://metacpan.org/author/PEVANS
http://www.leonerd.org.uk/ | https://www.tindie.com/stores/leonerd/
