On Fri, 22 Sep 2023 08:29:41 -0700 Russ Allbery <[email protected]> wrote:
> "Paul \"LeoNerd\" Evans" <[email protected]> writes: > > Ah curious - I'd be happy to hear ideas. > > One of the things I've wanted from nearly the start was some way of > marking up metasyntactic variables. POD is full of things like: > > perl <file> > > or: > > push ARRAY,LIST > > or the like, using various conventions mostly done via plain text, but > with proper markup they could get different formatting, different > colors in Pod::Text::Color, etc. Right now, some places use italics, > some use all caps, some use angle brackets, some don't mark them at > all, etc. I'm not quite sure I get what you mean here. > The hardest thing about maintaining Pod::Man is that there are a > bunch of things that it is supposed to do to help not require > excessive markup of Perl code, including complicated rules about > which C<> blocks get quotes around them, but those rules all assume > Perl. Right now, people have to pass in flags to pod2man to disable > the guesswork that doesn't apply to their documentation. I'm not > sure how this could be fixed with better semantic markup without > clusttering POD with a ton of markup, but I feel like it should be > possible. Hmmm - I wonder if there'd be merit in adding another code - perhaps T<text> inspired by HTML's `<tt>`, to suggest "here is fixedwidth but don't presume it to be Perl". Much like my related thoughts about `=code perl` vs `=code` or whatever... > Also, I know most folks here know this, but a reminder that people > use POD for a ton of things that are entirely unrelated to Perl, in > part because it's one of the easiest ways to write man pages without > having to learn an obscure formatting language and without having to > write a ton of impossibly verbose semantic markup. Yes indeed - I use it all the time for just such a purpose. > Tables are an obvious thing to add and presumably can be implemented > natively in *roff although I have never used tbl and it might be a > fair bit of work. Implementing them for Pod::Text sounds really > hard, but maybe it won't be as bad as I'm fearing or someone else > will do it for me. Youknow, we recently added Term::Table to perl core as a dependency of Test2::Suite; but it would make easy work of rendering tables out of POD as well. > I would like there to be a POD command for indicating the license of > the POD file itself so that the license text could be included in > output formats that support embedded comments, such as *roff and > HTML. Not sure what to do with the license in Pod::Text, but I think > this would be better than putting the license of the POD file in the > user-visible text like everyone does now. Really, that should be the > license of the thing the POD file is documenting, since that's what > the user is reading about, and that's often not the same as the > license of the POD. I could imagine a few things on that note. Maybe =meta licence GFDL =meta copyright Author Name, 2023 Gives an easy place to hang on other things that might be useful for things like POD->HTML or POD->nroff conversion too, e.g. =meta title Here Is My Lovely Document > There was a fairly fleshed out proposal a while back for footnote > support that never went anywhere. Ahyes - footnotes. I had forgotten about them. They'll be fun for me to implement in App::sdview::Output::Tickit, and then think about what POD formatting for them might look like. A task for future-me I feel... -- Paul "LeoNerd" Evans [email protected] | https://metacpan.org/author/PEVANS http://www.leonerd.org.uk/ | https://www.tindie.com/stores/leonerd/
