move chapters out of resources/ folder

[umlaeute]

this has been bothering me for ages (since the manual overhaul).

conceptually, i think that the manual consists of a collection of HTML pages.
these HTML pages are then enhanced by some assets, that is: images and CSS

but when i navigate to pd/doc/1.manual, then i do not see these chapters.
instead i only see the index.htm site, and a catch-all resources/ directory (which I take to include the assets)

i understand that as per #240 this is fully intentional:

So let's call them "chapter1", "chapter2", etc, and also move it to the 'resources' folder.

but i really don't agree with "chapters" being mere resources: they are the actual manual.
as such they should be in

(you could argue that the index.htm page is more of a resource: it helps us navigate the the chapters, but that's about it.)

i understand that the idea for the re-organization was:

• cleanup the directory structure (so the users do not get overhelmed)
• pick meaningful names (x2.htm -> chapter5.htm)

but if we put the chapters into the resources/ directory, little is won: they are again buried in files (there are 6 html files, and 114 other files in that directory).

i would like to suggest to move the chapter*.htm up one level into the pd/doc/1.manual/.

i guess the only reason to put them into the resources/ folder was to have index.htm as the first entry in the directoy (and chapter sorts alphabetically before index)

[Ant1r]

the chapter*.htm could alternatively go to a new chapters/ directory?

[millerpuckette]

Or better yet, as Iohannes suggests, just put them back in the doc/1.manual section.  It's totally reasonable to have them where they're easy to find individually. cheers Miller

…

On 7/31/25 2:39 PM, Antoine Rousseau wrote: *Ant1r* left a comment (pure-data/pddp#296) <https://urldefense.com/v3/__https://github.com/pure-data/pddp/issues/296*issuecomment-3139805447__;Iw!!Mih3wA!GlBB2j6yVDEz851dLCYwoynMTvJ_-JIenhuIwJttuJumAHnko_7EArclodjNbhe6vNlQ-PMXZnLgURO9ffnO$> the |chapter*.htm| could alternatively go to a new |chapters/| directory? — Reply to this email directly, view it on GitHub <https://urldefense.com/v3/__https://github.com/pure-data/pddp/issues/296*issuecomment-3139805447__;Iw!!Mih3wA!GlBB2j6yVDEz851dLCYwoynMTvJ_-JIenhuIwJttuJumAHnko_7EArclodjNbhe6vNlQ-PMXZnLgURO9ffnO$>, or unsubscribe <https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AARTRY2F7NVAG7B3DL2K4JL3LIE67AVCNFSM6AAAAACCZVVKJKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTCMZZHAYDKNBUG4__;!!Mih3wA!GlBB2j6yVDEz851dLCYwoynMTvJ_-JIenhuIwJttuJumAHnko_7EArclodjNbhe6vNlQ-PMXZnLgUZJEets0$>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[porres]

i guess the only reason to put them into the resources/ folder was to have index.htm as the first entry in the directory (and chapter sorts alphabetically before index)

yup

It's totally reasonable to have them where
they're easy to find individually.

It is, I agree.

How about we sort the alphabetically preceded with a number?

0-index.htm
1-Introduction.htm
2-Theory-of-operation.htm
3-Installing-configuring.htm
4-Externals.htm
5-Current-status.htm
6-Building-from-source.htm

i understand that the idea for the re-organization was:
cleanup the directory structure (so the users do not get overhelmed)
pick meaningful names (x2.htm -> chapter5.htm)

yup, and actually "chapters" isn't all too meaningful and the above option is very very very descriptive

[millerpuckette]

"index.htm" is a special name (web servers look for it and show it instead of the containing directory). But it's fine to have "index" show up as the _last_ entry, like an old-style table of contents in French :) cheers M

…

On 8/2/25 7:33 AM, porres wrote: *porres* left a comment (pure-data/pddp#296) <https://urldefense.com/v3/__https://github.com/pure-data/pddp/issues/296*issuecomment-3146240536__;Iw!!Mih3wA!FOeFvwqBaGsxPLeQIhpJVg54S2YBc0lROMe61gBFdQVhyNC_VUwglGb0T_1iBHDZQNWGwfEiuFiON3uqWy-O$> i guess the only reason to put them into the resources/ folder was to have index.htm as the first entry in the directory (and chapter sorts alphabetically before index) yup It's totally reasonable to have them where they're easy to find individually. It is, I agree. How about we sort the alphabetically preceded with a number? 0-index.htm 1-Introduction.htm 2-Theory-of-operation.htm 3-Installing-configuring.htm 4-Externals.htm 5-Current-status.htm 6-Building-from-source.htm i understand that the idea for the re-organization was: cleanup the directory structure (so the users do not get overhelmed) pick meaningful names (x2.htm -> chapter5.htm) yup, and actually "chapters" isn't all too meaningful and the above option is very very very descriptive — Reply to this email directly, view it on GitHub <https://urldefense.com/v3/__https://github.com/pure-data/pddp/issues/296*issuecomment-3146240536__;Iw!!Mih3wA!FOeFvwqBaGsxPLeQIhpJVg54S2YBc0lROMe61gBFdQVhyNC_VUwglGb0T_1iBHDZQNWGwfEiuFiON3uqWy-O$>, or unsubscribe <https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AARTRY7DNDKQQZXNRWOH5MT3LRETNAVCNFSM6AAAAACCZVVKJKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTCNBWGI2DANJTGY__;!!Mih3wA!FOeFvwqBaGsxPLeQIhpJVg54S2YBc0lROMe61gBFdQVhyNC_VUwglGb0T_1iBHDZQNWGwfEiuFiON7d4J9DC$>. You are receiving this because you commented.Message ID: ***@***.***>

[porres]

Ok, then...

1-Introduction.htm
2-Theory-of-operation.htm
3-Installing-configuring.htm
4-Externals.htm
5-Current-status.htm
6-Build-from-source.htm
index.htm

[ben-wes]

quick update here, @porres: porres/pure-data#100

... i do like the descriptive filenames - could be simply changed with some more search/replace for all files here. but i'd prefer to keep the "chapter" description as well. and maybe lowercase is acceptable (and more consistent with index)? and underscore might be more readable?

chapter1_introduction.htm
chapter2_theory_of_operation.htm
chapter3_installing_configuring.htm
chapter4_externals.htm
chapter5_current_status.htm
chapter6_building_from_source.htm
index.htm

[porres]

i'd prefer to keep the "chapter" description as well

I feel that makes the name too long and may not fit well into the "help browser"

[ben-wes]

may not fit well into the "help browser"

you're right - shouldn't be much more than this:

... now wondering whether naming like 1.introduction.htm and 2.theory.of.operation.htm would be more "correct" here (based on existing folder names and filenames).

[ben-wes]

seems ok to me:

... all variations are in the PR.