zsh-workers
 help / color / mirror / code / Atom feed
* I'd like to help maintain the Zsh Web Page
@ 2021-03-27 17:07 Austin Traver
  2021-03-27 20:57 ` Daniel Shahaf
  2021-03-29  0:02 ` Oliver Kiddle
  0 siblings, 2 replies; 9+ messages in thread
From: Austin Traver @ 2021-03-27 17:07 UTC (permalink / raw)
  To: zsh-workers

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

Hello,

My name is Austin. I'm a graduate student in the United States, studying computer science. I have been Zsh for a few years now, and I've become quite passionate about it, sharing my knowledge so far <https://helpful.wiki/zsh> with others along the way.

I'd like to help maintain the Zsh site, as I think reliable, usable documentation plays a vital role in understanding software. 

Is there any job, big or small, that you could think of, for me?

Best,
Austin

P.S.: How many people are on the Zsh workers list?

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: I'd like to help maintain the Zsh Web Page
  2021-03-27 17:07 I'd like to help maintain the Zsh Web Page Austin Traver
@ 2021-03-27 20:57 ` Daniel Shahaf
  2021-03-27 20:59   ` Daniel Shahaf
  2021-03-29  0:02 ` Oliver Kiddle
  1 sibling, 1 reply; 9+ messages in thread
From: Daniel Shahaf @ 2021-03-27 20:57 UTC (permalink / raw)
  To: Austin Traver; +Cc: zsh-workers

Austin Traver wrote on Sat, Mar 27, 2021 at 10:07:21 -0700:
> My name is Austin. I'm a graduate student in the United States,
> studying computer science. I have been Zsh for a few years now, and
> I've become quite passionate about it, sharing my knowledge so far
> <https://helpful.wiki/zsh> with others along the way.
> 

Welcome!

> I'd like to help maintain the Zsh site, as I think reliable, usable
> documentation plays a vital role in understanding software. 

Thanks!

> Is there any job, big or small, that you could think of, for me?

How about extending the documentation of the 'functions' builtin for the
issues mentioned in workers/48147 and its thread?  In a nutshell, the
examples in zshbuiltins(1) under `functions -M` cause the function's
return code to be non-zero when the arithmetic expression evaluates to
zero, which is problematic under «set -e», moreover, simply adding
«return 0» at the end of the function would break it.

The manual's sources are in Doc/Zsh/*.yo in the main repository.  If
it's not clear how to edit and build them, then our developer
documentation may be in need of attention, too ☺

> P.S.: How many people are on the Zsh workers list?

About 300.

Cheers,

Daniel


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: I'd like to help maintain the Zsh Web Page
  2021-03-27 20:57 ` Daniel Shahaf
@ 2021-03-27 20:59   ` Daniel Shahaf
  0 siblings, 0 replies; 9+ messages in thread
From: Daniel Shahaf @ 2021-03-27 20:59 UTC (permalink / raw)
  To: Austin Traver; +Cc: zsh-workers

Daniel Shahaf wrote on Sat, 27 Mar 2021 20:57 +00:00:
> Austin Traver wrote on Sat, Mar 27, 2021 at 10:07:21 -0700:
> > I'd like to help maintain the Zsh site, as I think reliable, usable
> > documentation plays a vital role in understanding software. 
> 
> Thanks!
> 
> > Is there any job, big or small, that you could think of, for me?
> 
> How about extending the documentation of the 'functions' builtin for the
> issues mentioned in workers/48147 and its thread?  In a nutshell, the
> examples in zshbuiltins(1) under `functions -M` cause the function's
> return code to be non-zero when the arithmetic expression evaluates to
> zero, which is problematic under «set -e», moreover, simply adding
> «return 0» at the end of the function would break it.
> 
> The manual's sources are in Doc/Zsh/*.yo in the main repository.  If
> it's not clear how to edit and build them, then our developer
> documentation may be in need of attention, too ☺

Note that the man pages and the HTML manual on https://zsh.sf.net/
are generated from the same sources.


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: I'd like to help maintain the Zsh Web Page
  2021-03-27 17:07 I'd like to help maintain the Zsh Web Page Austin Traver
  2021-03-27 20:57 ` Daniel Shahaf
@ 2021-03-29  0:02 ` Oliver Kiddle
  2021-03-29  0:39   ` Austin Traver
  2021-03-29  7:24   ` Daniel Shahaf
  1 sibling, 2 replies; 9+ messages in thread
From: Oliver Kiddle @ 2021-03-29  0:02 UTC (permalink / raw)
  To: Austin Traver; +Cc: zsh-workers

Austin Traver wrote:
> My name is Austin. I'm a graduate student in the United States, studying
> computer science. I have been Zsh for a few years now, and I've become quite
> passionate about it, sharing [1]my knowledge so far with others along the way.
>
> I'd like to help maintain the Zsh site, as I think reliable, usable
> documentation plays a vital role in understanding software. 
>
> Is there any job, big or small, that you could think of, for me?

Aside from the documentation, the design, structure, layout and
content of the web pages could do with updating, modernising and being
maintained over the longer term.

It'd be quite nice to unify what we have at https://www.zsh.org/ with
http://zsh.sourceforge.net/ so that sourceforge is just a mirror of the
other URL and preserving content from both.

The current site is done in old hand-written HTML that hasn't
changed much ever. It is probably best to keep the design relatively
conservative - the 1995-era design looks less bad now than a 2005 one
would. Preferably no cookies or required JavaScript but a touch of CSS
wouldn't do much harm. A markdown based static templating preprocessor
such as jekyll would be fine if it can run on the existing hosting
without complicated install procedures. Currently, there is a certain
amount of duplicated boiler-plate HTML.

If you or whoever else is interested, I can point you in the direction
of relevant git repositories where the existing content sits.

Oliver


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: I'd like to help maintain the Zsh Web Page
  2021-03-29  0:02 ` Oliver Kiddle
@ 2021-03-29  0:39   ` Austin Traver
  2021-03-29  1:20     ` Oliver Kiddle
  2021-03-29  7:24   ` Daniel Shahaf
  1 sibling, 1 reply; 9+ messages in thread
From: Austin Traver @ 2021-03-29  0:39 UTC (permalink / raw)
  To: Oliver Kiddle; +Cc: zsh-workers

I'm absolutely interested. I think 

> It is probably best to keep the design relatively
> conservative - the 1995-era design looks less bad now than a 2005 one
> would. Preferably no cookies or required JavaScript but a touch of CSS
> wouldn't do much harm. A markdown based static templating preprocessor
> such as jekyll would be fine if it can run on the existing hosting
> without complicated install procedures.

I feel the exact same way. Markdown is a great fit.

As far as using Jekyll, I think Hugo is a better choice for long term reliability. But anyhow, post processing is getting ahead of ourselves. I'd need to start by replicating the documentation in the equivalent markdown.

What repositories host the Zsh documentation, is there a clone on GitHub I can fork?

Best,
Austin

> On Mar 28, 2021, at 5:02 PM, Oliver Kiddle <opk@zsh.org> wrote:
> 
> Austin Traver wrote:
>> My name is Austin. I'm a graduate student in the United States, studying
>> computer science. I have been Zsh for a few years now, and I've become quite
>> passionate about it, sharing [1]my knowledge so far with others along the way.
>> 
>> I'd like to help maintain the Zsh site, as I think reliable, usable
>> documentation plays a vital role in understanding software. 
>> 
>> Is there any job, big or small, that you could think of, for me?
> 
> Aside from the documentation, the design, structure, layout and
> content of the web pages could do with updating, modernising and being
> maintained over the longer term.
> 
> It'd be quite nice to unify what we have at https://www.zsh.org/ with
> http://zsh.sourceforge.net/ so that sourceforge is just a mirror of the
> other URL and preserving content from both.
> 
> The current site is done in old hand-written HTML that hasn't
> changed much ever. It is probably best to keep the design relatively
> conservative - the 1995-era design looks less bad now than a 2005 one
> would. Preferably no cookies or required JavaScript but a touch of CSS
> wouldn't do much harm. A markdown based static templating preprocessor
> such as jekyll would be fine if it can run on the existing hosting
> without complicated install procedures. Currently, there is a certain
> amount of duplicated boiler-plate HTML.
> 
> If you or whoever else is interested, I can point you in the direction
> of relevant git repositories where the existing content sits.
> 
> Oliver


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: I'd like to help maintain the Zsh Web Page
  2021-03-29  0:39   ` Austin Traver
@ 2021-03-29  1:20     ` Oliver Kiddle
  2021-03-29  3:39       ` Austin Traver
  0 siblings, 1 reply; 9+ messages in thread
From: Oliver Kiddle @ 2021-03-29  1:20 UTC (permalink / raw)
  To: Austin Traver; +Cc: zsh-workers

Austin Traver wrote:
> I feel the exact same way. Markdown is a great fit.

> I'd need to start by replicating the documentation in the equivalent
> markdown.

The actual documentation is something of a different matter. That's not
written in HTML but in a macro language named yodl that converts to any
of man pages, HTML or texinfo (from which it can be rendered to PDF,
info pages and other formats). The man pages are possibly the most
important form for the documentation. 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'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.

> What repositories host the Zsh documentation, is there a clone on GitHub I can fork?

The documentation is in a Doc directory alongside the source 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


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: I'd like to help maintain the Zsh Web Page
  2021-03-29  1:20     ` Oliver Kiddle
@ 2021-03-29  3:39       ` Austin Traver
  2021-04-07  8:19         ` Austin Traver
  0 siblings, 1 reply; 9+ messages in thread
From: Austin Traver @ 2021-03-29  3:39 UTC (permalink / raw)
  To: Oliver Kiddle; +Cc: zsh-workers

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


> 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
> 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: 3006 bytes --]

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: I'd like to help maintain the Zsh Web Page
  2021-03-29  0:02 ` Oliver Kiddle
  2021-03-29  0:39   ` Austin Traver
@ 2021-03-29  7:24   ` Daniel Shahaf
  1 sibling, 0 replies; 9+ messages in thread
From: Daniel Shahaf @ 2021-03-29  7:24 UTC (permalink / raw)
  To: Oliver Kiddle; +Cc: Austin Traver, zsh-workers

Oliver Kiddle wrote on Mon, Mar 29, 2021 at 02:02:22 +0200:
> Austin Traver wrote:
> > My name is Austin. I'm a graduate student in the United States, studying
> > computer science. I have been Zsh for a few years now, and I've become quite
> > passionate about it, sharing [1]my knowledge so far with others along the way.
> >
> > I'd like to help maintain the Zsh site, as I think reliable, usable
> > documentation plays a vital role in understanding software. 
> >
> > Is there any job, big or small, that you could think of, for me?
> 
> Aside from the documentation, the design, structure, layout and
> content of the web pages could do with updating, modernising and being
> maintained over the longer term.
> 
> It'd be quite nice to unify what we have at https://www.zsh.org/ with
> http://zsh.sourceforge.net/ so that sourceforge is just a mirror of the
> other URL and preserving content from both.

We could start by integrating the data in the zsh.org page (the list of
mirrors) into the zsh.sf.net site.  Then we could simply run the rsync
command from zsh-web/README against the zsh.org DocumentRoot, or better
yet, give the RM SSH access and group permissions so they can do that
themselves.  (We'll anyway need to give the RM some way to upload
artifacts.)

> The current site is done in old hand-written HTML that hasn't
> changed much ever. It is probably best to keep the design relatively
> conservative - the 1995-era design looks less bad now than a 2005 one
> would.

It certainly meets the "Don't break anything" criterion: doesn't break
screen readers or custom colour schemes, doesn't break mouseless usage,
doesn't require javascript…

> Preferably no cookies or required JavaScript but a touch of CSS
> wouldn't do much harm. A markdown based static templating preprocessor
> such as jekyll would be fine if it can run on the existing hosting
> without complicated install procedures. Currently, there is a certain
> amount of duplicated boiler-plate HTML.
> 
> If you or whoever else is interested, I can point you in the direction
> of relevant git repositories where the existing content sits.
> 
> Oliver
> 


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: I'd like to help maintain the Zsh Web Page
  2021-03-29  3:39       ` Austin Traver
@ 2021-04-07  8:19         ` Austin Traver
  0 siblings, 0 replies; 9+ messages in thread
From: Austin Traver @ 2021-04-07  8:19 UTC (permalink / raw)
  To: zsh-workers; +Cc: Daniel Shahaf, Oliver Kiddle

[-- 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 --]

^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2021-04-07  8:19 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-03-27 17:07 I'd like to help maintain the Zsh Web Page Austin Traver
2021-03-27 20:57 ` Daniel Shahaf
2021-03-27 20:59   ` Daniel Shahaf
2021-03-29  0:02 ` Oliver Kiddle
2021-03-29  0:39   ` Austin Traver
2021-03-29  1:20     ` Oliver Kiddle
2021-03-29  3:39       ` Austin Traver
2021-04-07  8:19         ` Austin Traver
2021-03-29  7:24   ` Daniel Shahaf

Code repositories for project(s) associated with this public inbox

	https://git.vuxu.org/mirror/zsh/

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).