Re: I'd like to help maintain the Zsh Web Page

[Austin Traver <austintraver@icloud.com>]

[-- Attachment #1: Type: text/plain, Size: 3092 bytes --]

As a start, I built a prototype.

I wrote a utility script of sorts, that takes the manpages from the source code, and the troff into Markdown.

I've added a preview of what zshcontrib(1) <https://github.com/austintraver/zsh/wiki/zshcontrib> looks like when it is converted to Markdown, and I've also posted a GitHub gist of the manpage <https://gist.github.com/austintraver/a89bc733752be4379eaa1daa59fe2368> when the script converts it back from Markdown into troff. Key takeaway: this utility script can convert the manpages bidirectionally between troff and Markdown.

This utility script is just a wrapper around Pandoc <https://pandoc.org/>, so it's nothing fancy, there's not much that would need to be maintained, and performing the conversions is designed to be straightforward enough as for anyone working on the project to be able to do so themselves.

Anyway, this is still a work in progress, so if you have any thoughts, or see any ways this tool could be improved, or a better way to apply the technology, I am all ears.

Best,
Austin

P.S.: Shout out to Oliver Kiddle and Daniel Shahaf, who took the time to welcome me into the project and give me important guidance/direction as I went about making my first contribution to the Zsh project.

> On Mar 28, 2021, at 08:39 PM, Austin Traver <austintraver@icloud.com> wrote:
> 
> 
>> The actual documentation is… not written in HTML but in a macro language named yodl
> 
> I've worked with groff in the past, so I'm at least acquainted with macro packages such as mdoc. Yodl, I'm still working on learning, but I see this as a chance to learn something new.
> 
>> The man pages are possibly the most
>> important form for the documentation.
> 
> I agree entirely, don't know what I'd do without them!
> 
>> I'm not sure whether that can be
>> replicated from markdown but it really would need to be. texi2html is
>> quite configurable if we just want to tweak the web version of the
>> documentation.
> 
> I'll make a first attempt using texi2html and let you guys know how it goes.
> 
>> I'm not saying it has to be this way forever but take the
>> time to understand it first so you don't end up doing a lot of work that
>> goes to waste.
> 
> In the past, I've learned the hard way what happens when developers build software now and understand requirements later. Not a fun time for anyone. I'll be sure to do this work in the correct order. 
> 
>> The documentation is in a Doc directory alongside the source code -
>> https://git.code.sf.net/p/zsh/code <https://git.code.sf.net/p/zsh/code>
>> There are mirrors on github and gitlab if you prefer.
>> Sourceforge website content is https://git.code.sf.net/p/zsh/web
>> zsh.org website content is only the one file, so curl or saving from
>> firefox is probably easiest.
>> 
>> Oliver
> 
> 
> 
> Sounds good! If I reach a checkpoint, I'll post it to https://github.com/austintraver/zsh <https://github.com/austintraver/zsh>
> Which remote (and branch) would I make a pull request to, when done? 
> 
> Best,
> Austin


[-- Attachment #2: Type: text/html, Size: 5474 bytes --]