search

Raku / user-experience

Identifying issues in and improving the Raku user experience
Artistic License 2.0
25 stars 5 forks source link

GitHub Pod Parsing/Rendering #35

Open AlexDaniel opened 5 years ago

AlexDaniel commented 5 years ago

Currently GitHub renders .pod6 files as text. It would be great if they were parsed and rendered properly as POD6 files (with proper HTML output).

Example: https://github.com/perl6/doc/blob/master/doc/Type/IO/Socket/INET.pod6

There was an attempt to implement that, but in the end it was rejected because perfect POD6 parsers need to execute the file in order to render it correctly. So it seems that we need a solution that doesn't run any code, and instead attempts to render POD6 according to some basic (existing) rules.

See previous ticket: https://github.com/perl6/doc/issues/167

AlexDaniel commented 5 years ago

I wonder if we can use https://github.com/perl6/atom-language-perl6/ (or any other basic perl6 parser) to output some pages. It doesn't have to be absolutely correct, just rendering some headings and paragraphs will do.

raiph commented 5 years ago

See also https://github.com/perl6/Pod-To-HTML/issues/55#issuecomment-451294186 (and the comment immediately preceding it which documents the original discussion of this issue in 2009). In my comment I propose a solution that I think is simple and requires no action on GH's part. It may be a non-starter for reasons I don't see -- it is a strawman proposal -- but if so, please say why.