Re: Documentation organization (was: Mirrors and code hosting)

[dana <dana@xxxxxxx>]

On Sat 20 Sep 2025, at 14:23, Clinton Bunch wrote:
> Do we want a /Doc/devel as well as /Doc/stable and /Doc/version?

i would like that personally

we would want to symlink stable (or w/e we call it) to the actual
version number so they're equivalent. and we would probably want to
disallow crawling of all of the non-stable urls so search engines don't
return outdated/confusing results

On Sat 20 Sep 2025, at 14:23, Clinton Bunch wrote:
> We
> could get a nightly cron script to pull the latest commits and rebuild
> the web documentation if anything in Doc or the FAQ have had changes
> committed.  (We could on some of the other platforms we're discussing
> use their own build pipelines to update our webpages and scp/rsync them
> to zsh.org)

something like that would be ideal. currently we just build and upload
the docs as part of the release process. it's not a huge problem with
how things currently are but it would become more annoying if the docs
were versioned and/or if we released more often

btw i already looked into expanding the current site to include
historical versions (Doc/5.8, Doc/5.7, etc). i made scripts to generate
them, move them into place, add noindex tags, etc. i think i didn't post
about it because we're supposed to commit the rendered docs to the web
repo and i was worried we wouldn't want to track all of that. but we
could look into it again if this project drags on or doesn't work out

On Sat 20 Sep 2025, at 14:23, Clinton Bunch wrote:
> Also I'm thinking of having two HTML and PDF outputs, one pretty for the
> primary and a second simpler set missing things like sidebar navigation
> and syntax highlighting of examples.  The second set would be what make
> docs would generate.  The idea being having a "pretty" site and one more
> accessible (screen readers, tty browsers, color-blind)  linked from the
> Documentation.html as simple format or accessible format, something like
> that. Thoughts?

it doesn't seem necessary to have two different outputs. if the html is
structured properly it should 'degrade' gracefully so that it works well
with screen readers and text-based browsers

as far as the pdf, tbh i would be surprised if anybody cares about it at
all. not suggesting we get rid of it but i wouldn't worry too much about
it either

dana