Zsh Mailing List Archive
Messages sorted by: Reverse Date, Date, Thread, Author

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



On 9/20/2025 11:52, Lawrence Velázquez wrote:
On Sat, Sep 20, 2025, at 12:33 AM, dana wrote:
On Fri 19 Sep 2025, at 11:57, Oliver Kiddle wrote:
Codeberg seems to be a good and popular choice these days. Someone
registered "zsh" on it not long ago. Would be good to know if that was
someone here or if we've lost the chance to use that.
i missed 'zsh' by less than a week but i did get 'zsh-org' and
'zsh-users' for continuity with gitlab and github

if we do like codeberg, and the 'zsh' person doesn't step forward
Perhaps Codeberg itself could assist with this?  Back when I was
more actively involved with MacPorts, I squatted "macports" on
GitHub on a whim but didn't tell anyone.  When the project decided
to move to GitHub, they must have contacted someone there because
an employee emailed me asking if I'd be willing to give up the
username.

we could carry on with one of those
I think it would look really amateurish for us to have to resort
to "zsh-org" or "zsh-users" as our official name.  Maybe I'm putting
too much weight on it, but to me it would feel worse than staying
on SourceForge, especially if we consolidate the website at zsh.org.

Maybe you could grab "zshell" at least?  (I just registered "zsh"
on SourceHut, just in case.)

the mirrors seem like w/e, since they're just source distributions i
assume 95% of visitors don't care about them either way
Presumably various distros have their own mirrors too.

it would be nice if we could avoid breaking the links to the actual docs
if at all possible. searchability is already kind of sub-optimal, it
would be a shame to make it worse. we could end up like bash where most
searches return absolutely nothing from the actual documentation unless
you explicitly add 'manual' to the search terms (sometimes not even
then)


btw, maybe this is too ot, but i've always wished that our documentation
was versioned, similar to how postgres does it:

https://www.postgresql.org/docs/devel/index.html
https://www.postgresql.org/docs/current/index.html
https://www.postgresql.org/docs/14/index.html
https://www.postgresql.org/docs/9.5/index.html
etc
+1 to all of this.

Do we want a /Doc/devel as well as /Doc/stable and /Doc/version? 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)

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?






Messages sorted by: Reverse Date, Date, Thread, Author