* 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 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
* 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
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).