From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-3.4 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,FREEMAIL_FROM,HTML_MESSAGE,MAILING_LIST_MULTI, RCVD_IN_DNSWL_MED,UNPARSEABLE_RELAY autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 30779 invoked from network); 7 Apr 2021 08:19:59 -0000 Received: from zero.zsh.org (2a02:898:31:0:48:4558:7a:7368) by inbox.vuxu.org with ESMTPUTF8; 7 Apr 2021 08:19:59 -0000 ARC-Seal: i=1; cv=none; a=rsa-sha256; d=zsh.org; s=rsa-20200801; t=1617783600; b=FUTxMi2gZ1K3KnrTtD9zFzx4gHjgrJFonKv1fqZOgIJ6Ocfr6TnIW2Qc6D5All91kLyL3aJr65 6Mjml0248vW31r9C4rcjJBJKZtVksohpOx8CaY1F58bXc11Mrp5I9oKDZqw2bJMmvpp4Th9qna glAqeUbEWvmoawK6aDxJsc/Zwd9gWV4hvyayk3vKK9BZuGDypqtA6+kl6oJYFCJhmSveuhbt+a PYVx/ZLxXF2gP8mvDCW9aFJpYEn7QM25Hq0K48d7SllqP5OecZQxTWXYhmE+g0zYbVZu3QcB4r Xvqg7XTrJb0u3dixdCI7C5ztzSNtYqHXhti9oQxLdLnyAg==; ARC-Authentication-Results: i=1; zsh.org; iprev=pass (mr85p00im-ztdg06011901.me.com) smtp.remote-ip=17.58.23.198; dkim=pass header.d=icloud.com header.s=1a1hai header.a=rsa-sha256; dmarc=pass header.from=icloud.com; arc=none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed; d=zsh.org; s=rsa-20200801; t=1617783600; bh=lXODs8QuKu7QTZ9R02lM7D/6L4DDW9UopuYx/EIXz0I=; h=List-Archive:List-Owner:List-Post:List-Unsubscribe:List-Subscribe:List-Help: List-Id:Sender:References:To:Cc:In-Reply-To:Date:Subject:MIME-Version: Content-Type:Message-ID:From:DKIM-Signature:DKIM-Signature; b=EUK0bFeonUe93k5aqyvhjknk5q+yQ4PKuCaM3atdmdgfBp8ZJrQNddLpdgfEt+ehtv/1MXIRqF 4ggkv3LmudT4mIfAzwYy2ltG+svEBNQmlhBZrR8G/SYQx8iIqGupnvb4RdRzuPb+dUkF7K8nIi wgEPJBEBVVQe6jEYLgheUwZGhmu48T/wRUzuN+lyfbhIIn9v91YhIG/Pqm6oFx1mPxGSrWe5Bl E3sDoGXC7Xw75Z2f41gYd4O3V1xQ9MztrD1Y9BtUkZ+b8RUFCH0ttLxnoCkFpemUUHNLh9maFS QGJbVJAWB+JTdpC6DxZfLU209cPd3x1LWVkzOkrJmlfRQw==; DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=zsh.org; s=rsa-20200801; h=List-Archive:List-Owner:List-Post:List-Unsubscribe: List-Subscribe:List-Help:List-Id:Sender:References:To:Cc:In-Reply-To:Date: Subject:Mime-Version:Content-Type:Message-Id:From:Reply-To: Content-Transfer-Encoding:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID; bh=7kv+9H8IoSdeQNhoWiDFIyAAEPsQVl4Q+tkGMXzhW3c=; b=d+Ylbicaf1RYa4XlMIrvIsAFYQ GyVzdxyWsXf0n8zvvKbdoNLgTkyhJjE48J8l4c5zZEoaVFi6aNGJ8gKkvfKJ2VK+xN1CKXgHQbPec 3iPGBMujO5Vl1wxNaWTOW+pQemLiDFDRTrA1Wp1KGixrqEJ6WyW0fUkcUbItSMqElNihzaSpz3qpU CocAej62IlJBZxXI/168nWSKzRd2aqSSkIJaKXHMifdCpR7u9lT5TLkNSo10vB361s21+PElhosWT hVrbNJbbi+kPO8bIdrRPaLTDkrB4XXQDHXu1wH1kKcoAcB/E9NWKNiuxLij2wforhhNVFJZ0VR8R4 rNvMa53w==; Received: from authenticated user by zero.zsh.org with local id 1lU3Pp-000572-3B; Wed, 07 Apr 2021 08:19:57 +0000 Authentication-Results: zsh.org; iprev=pass (mr85p00im-ztdg06011901.me.com) smtp.remote-ip=17.58.23.198; dkim=pass header.d=icloud.com header.s=1a1hai header.a=rsa-sha256; dmarc=pass header.from=icloud.com; arc=none Received: from mr85p00im-ztdg06011901.me.com ([17.58.23.198]:35087) by zero.zsh.org with esmtps (TLS1.2:ECDHE-RSA-AES256-GCM-SHA384:256) id 1lU3PW-0004rD-Pv; Wed, 07 Apr 2021 08:19:39 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=icloud.com; s=1a1hai; t=1617783577; bh=7kv+9H8IoSdeQNhoWiDFIyAAEPsQVl4Q+tkGMXzhW3c=; h=From:Message-Id:Content-Type:Mime-Version:Subject:Date:To; b=cQQQGshHpfDgVadY1izvC1U257C7HDDjtbm5+F+ubOD4yfAOuA6/EtjwBD6cZdl2A CZEtjQ2FL5riiwFG8ru8+SITXsNimW43A0T9CW+dZpFYYtiNqcwWNUtMQH+W5a6sgA arqhzzj9B6DGTi0AKEz1Pv2nCYEzOJqrNQNnGBgHfn3h+wE/zgnpQt0vixKoeLO8hz eDnuTZTrSLECcrP8U55bsDZQlbui6y9y7horVFLRQyQr7lyHtAS7Cskt1l4jkwEiJa rAP8CpFJ8KJts8zIU3VWmZngGsjeQUXl2elSIaBgKbfY3QQRuq7NyXTTTo5+2BKaog /TMpTgQcklZAg== Received: from [100.65.21.70] (unknown [64.136.145.104]) by mr85p00im-ztdg06011901.me.com (Postfix) with ESMTPSA id E779EA60B77; Wed, 7 Apr 2021 08:19:36 +0000 (UTC) From: Austin Traver Message-Id: Content-Type: multipart/alternative; boundary="Apple-Mail=_9B45EB3C-C41A-46DE-96D3-8C810BEC6D0E" Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.60.0.2.21\)) Subject: Re: I'd like to help maintain the Zsh Web Page Date: Wed, 7 Apr 2021 01:19:36 -0700 In-Reply-To: Cc: Daniel Shahaf , Oliver Kiddle To: zsh-workers@zsh.org References: <81983-1616976142.953383@GxW7.Jtw5.jOhI> <481B0356-2B76-415A-8C1E-2BB6828420FC@icloud.com> <84773-1616980819.919111@ybx2.QGzt.Gdnm> X-Mailer: Apple Mail (2.3654.60.0.2.21) X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:6.0.369,18.0.761 definitions=2021-04-07_04:2021-04-06,2021-04-07 signatures=0 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1011 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-2009150000 definitions=main-2104070060 X-Seq: 48417 Archived-At: X-Loop: zsh-workers@zsh.org Errors-To: zsh-workers-owner@zsh.org Precedence: list Precedence: bulk Sender: zsh-workers-request@zsh.org X-no-archive: yes List-Id: List-Help: List-Subscribe: List-Unsubscribe: List-Post: List-Owner: List-Archive: --Apple-Mail=_9B45EB3C-C41A-46DE-96D3-8C810BEC6D0E Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 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) = looks like when it = is converted to Markdown, and I've also posted a GitHub gist of the = manpage = = 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 = , 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 = wrote: >=20 >=20 >> The actual documentation is=E2=80=A6 not written in HTML but in a = macro language named yodl >=20 > 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. >=20 >> The man pages are possibly the most >> important form for the documentation. >=20 > I agree entirely, don't know what I'd do without them! >=20 >> 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. >=20 > I'll make a first attempt using texi2html and let you guys know how it = goes. >=20 >> 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. >=20 > 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.=20 >=20 >> 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. >>=20 >> Oliver >=20 >=20 >=20 > Sounds good! If I reach a checkpoint, I'll post it to = https://github.com/austintraver/zsh = > Which remote (and branch) would I make a pull request to, when done?=20= >=20 > Best, > Austin --Apple-Mail=_9B45EB3C-C41A-46DE-96D3-8C810BEC6D0E Content-Transfer-Encoding: quoted-printable Content-Type: text/html; charset=utf-8 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) looks like when it is converted to = Markdown, and I've also posted a GitHub gist of the manpage 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, 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=E2=80=A6 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
Which = remote (and branch) would I make a pull request to, when = done? 

Best,
Austin

= --Apple-Mail=_9B45EB3C-C41A-46DE-96D3-8C810BEC6D0E--