Front page | perl.perl5.porters |
Postings from November 2021
On Fri, 12 Nov 2021 13:54:02 +0000 Neil Bowers <neilb@neilb.org> wrote: > Markdown has long since won the battle of simple text-based > documentation formats. People, not just developers, are used to > writing it in lots of different places. Odds are that developers > trying out Perl, coming from other language experience, will be > familiar with markdown, and pod will just seem weird. Even when I'm writing POD I often end up doing `this`.. ohwait I meant C<this>. > There are some things that pod provides that markdown doesn’t, and > there’s the whole table issue. But on the very rare occasion I’ve > wanted a table in documentation I’ve used a manually formatted ASCII > table. And most modules have fairly simple documentation, in terms of > the pod syntax currently used. Tables++ (really I want tables) > The biggest problem I’m aware of is that this would require > coordination of changes in multiple places, and I don’t even know > what all of those places are. > And there are different markdown formats, so we’d have to pick one. Yes, that's always an issue. On a somewhat-tangential note, I lately have been maintaining a tool designed to be "a better man(1)", able to view POD, Markdown, nroff etc... with a real native formatter that understands terminal bold/underline/italics, colour, etc... https://twitter.com/cpan_pevans/status/1405938689050656774 https://metacpan.org/dist/App-sdview As well as display, it also has some code to output to various formats, so it can act as a decent cross-converter between these formats. If you are looking for more inspiration on how to handle these things, that might be another good place to look. -- Paul "LeoNerd" Evans leonerd@leonerd.org.uk | https://metacpan.org/author/PEVANS http://www.leonerd.org.uk/ | https://www.tindie.com/stores/leonerd/Thread Previous | Thread Next