Raku / doc

🦋 Raku documentation
https://docs.raku.org/
Artistic License 2.0
290 stars 293 forks source link

=config discussion from S26 is missing #4514

Open tbrowder opened 2 months ago

tbrowder commented 2 months ago

Problem or new feature

For Pod6, add the missing text from S26 about adding separate config information for the whole document or as a one-liner.

Add examples.

NOTE: I am looking in the docs but can't find it--but it may be there.

If it's not, I'll file PR.

coke commented 2 months ago

RAKUDO_POD_DECL_BLOCK_USER_FORMAT is not a language-spec'd env var, correct? It is listed here which I found with the google search.

https://docs.raku.org/language/pod

Note that S26 isn't "the spec" so if there's still items in there that are missing from the docs, it isn't necessarily a bug. Verify that something is referenced in roast

If it's rakudo specific (and therefore not spec), we need to include text to that effect when adding it (As was done for dd or this item on that page) -

This item could definitely get an index to make it easier to search for.

finanalyst commented 2 months ago

@tbrowder Please refer to Rendering of new RakuDoc v2. This has quite an extensive explanation of =config. My new renderer handles (almost) all of RakuDoc v2. The current flaws are due to some peculiarities of Raku documentation, eg using X<> markup in =head blocks. The core renderer handles the markup well, but the HTML being generated is not escaping things properly.

RAKUDO_POD_DECL_BLOCK_USER_FORMAT is not mentioned at all in RakuDoc v2 because =config is expanded.