develooper Front page | perl.perl6.users | Postings from March 2021

Alternative view of Raku Documentation

Thread Next
From:
Richard Hainsworth
Date:
March 2, 2021 12:45
Subject:
Alternative view of Raku Documentation
Message ID:
54ad17ef-fb0c-f689-3716-1f191b32b4f8@gmail.com
I've just passed a milestone in the development of a suite of modules 
for rendering a collection of POD6 content files.

Please take a look at http://raku.finanalyst.org and especially 
http://raku.finanalyst.org/search.html

Please let me know whether you find the search interface easier than the 
one on the official site.

(I will be updating based on feedback. Eg., I will be showing links and 
visited links more clearly, but not with blue/purple of standard HTML)

Both search functions (the official one, and mine) rely on the same 
underlying information, but it is presented in a different way. I wanted 
(a) more context when searching, (b) I want previous searches to be 
retained in case the place I went to does not have the information  was 
looking for.

Please also bear in mind that this is a system still being developed. So 
there are some wrinkles:

1: There are numerous places in the official Raku docs where links 
target 'virtual' files. These virtual files do not exist in the 
Raku/docs directory, but are generated by the software developed to 
render the POD6 files, namely Documentable. Personally, I think having 
links to virtual files is fragile, and it does make the development of 
an alternative system of viewing the docs more difficult.

2: The inheritance diagrams in the standard documentation system are not 
cited in the official Raku docs, but are "sewn in" by Documentable based 
on a single text file that describes relationships.

The reasons I developed this new system?

- I want to create a Blog site, a site for translations from English to 
Welsh, and a site for my business that rely mostly on Raku, not php.

- The underlying content of most CMS suites seems to be MarkDown. But 
MarkDown does not allow for any meta data to be attached to text. POD6 
is both simple to write, but it also allows for meta data to be attached 
to paragraphs, headers, blocks. You can see some of this potential by 
clicking on the Collection button at raku.finanalyst.org

- I'm not entirely happy with the Documentable/Pod::To::HTML modules 
that are used to render Raku Documentation, and I hate it when people 
criticise things without providing some systematic alternative. So 
here's an alternative.

I have more to say about Module documentation, but that involves another 
topic.


Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About