Source files for documentation? #30

Would it be possible to include the source files (*.pp, *.pm, directory-require.rkt) for the documentation?

This will result in a smoother learning curve because the Pollen documentation seems to use more functionality than is covered in the tutorials at this date. For example the (seemingly?) automatic numbering of chapters and paragraphs.

Would it be possible to include the source files (*.pp, *.pm, directory-require.rkt) for the documentation? This will result in a smoother learning curve because the Pollen documentation seems to use more functionality than is covered in the tutorials at this date. For example the (seemingly?) automatic numbering of chapters and paragraphs.

The source files for the documentation are included. But they’re not written in Pollen. Rather, they’re made with scribble/manual, Racket’s documentation language.

The source files for the documentation [are included](https://github.com/mbutterick/pollen/tree/master/scribblings). But they’re not written in Pollen. Rather, they’re made with `scribble/manual`, Racket’s documentation language.

PS. Though Pollen is derived from Scribble, it can’t do everything that Scribble can, nor vice versa. As a documentation language by design, Scribble has better capabilities in collecting cross-references, generating TOCs and indexes, etc. Pollen’s strength is its support for free-form markup and automation via tag functions.

I would consider adding chapter / paragraph numbering to Pollen. I’d just need a more concrete explanation of how the function ought to work. Compared to Scribble, Pollen tries to minimize entanglements between pages, which keeps things cleaner and also makes it possible to render each page independently.

For instance, with chapter numbering, it would be simple to add a function to directory-require.rkt that has a list of the chapter headings and computes title-to-number mapping on demand. When a page is rendered, it asks that function for the appropriate title and number.

PS. Though Pollen is derived from Scribble, it can’t do everything that Scribble can, nor vice versa. As a documentation language by design, Scribble has better capabilities in collecting cross-references, generating TOCs and indexes, etc. Pollen’s strength is its support for free-form markup and automation via tag functions. I would consider adding chapter / paragraph numbering to Pollen. I’d just need a more concrete explanation of how the function ought to work. Compared to Scribble, Pollen tries to minimize entanglements between pages, which keeps things cleaner and also makes it possible to render each page independently. For instance, with chapter numbering, it would be simple to add a function to `directory-require.rkt` that has a list of the chapter headings and computes title-to-number mapping on demand. When a page is rendered, it asks that function for the appropriate title and number.

It would also be simple to generate a number for a heading / page based on its position in index.ptree (or other pagetree file).

It would also be simple to generate a number for a heading / page based on its position in `index.ptree` (or other pagetree file).

Labels Milestones

Source files for documentation? #30