From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 13828 invoked by alias); 11 Sep 2017 12:15:31 -0000 Mailing-List: contact zsh-users-help@zsh.org; run by ezmlm Precedence: bulk X-No-Archive: yes List-Id: Zsh Users List List-Post: List-Help: X-Seq: 22894 Received: (qmail 4112 invoked by uid 1010); 11 Sep 2017 12:15:30 -0000 X-Qmail-Scanner-Diagnostics: from aok120.rev.netart.pl by f.primenet.com.au (envelope-from , uid 7791) with qmail-scanner-2.11 (clamdscan: 0.99.2/21882. spamassassin: 3.4.1. Clear:RC:0(85.128.245.120):SA:0(-1.9/5.0):. Processed in 9.749458 secs); 11 Sep 2017 12:15:30 -0000 X-Spam-Checker-Version: SpamAssassin 3.4.1 (2015-04-28) on f.primenet.com.au X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,T_SPF_HELO_TEMPERROR autolearn=ham autolearn_force=no version=3.4.1 X-Envelope-From: psprint@zdharma.org X-Qmail-Scanner-Mime-Attachments: | X-Qmail-Scanner-Zip-Files: | X-Virus-Scanned: by amavisd-new using ClamAV (11) Date: Mon, 11 Sep 2017 14:15:12 +0200 From: Sebastian Gniazdowski To: "Nikolay Aleksandrovich Pavlov (ZyX)" , Zsh Users Message-ID: In-Reply-To: <2669581505036634@web1j.yandex.ru> References: <2669581505036634@web1j.yandex.ru> Subject: Re: Doxygen for shell scripts X-Mailer: Airmail (442) MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Content-Disposition: inline On 10.09.2017 at 11:43:54, Nikolay Aleksandrovich Pavlov (ZyX) (kp-pav=40= yandex.ru) wrote: > Why not a sphinx plugin=3F It is most logical: you need to teach it how= to extract documentation =20 > comments and whatever those =E2=80=9Cmore things=E2=80=9D you want and = it takes the job of yielding nicely =20 > formatted documentation in many different formats (one of which include= s man pages), =20 There's a problem with this route =E2=80=93 zsd uses (z) flag, which appa= rently exposes the original parser used by Zsh. So it's easy to parse and= this is robust, because the parser has enough attention from developers.= With Sphinx I would have to write own parser in Python. This is for sure= doable, especially because shell syntax has multiple simplifications (li= ke: require space after =5B=5B in condition =5B=5B ... =5D=5D), but A=46A= IK nobody has done this yet, so no resources, examples, etc. I think many= people had this idea, to write doxygen-like tool or something similar fo= r shell scripts, but everybody stepped down because of the parser effort = and doubts if shell scripts are sophisticated enough to address them. Zsh= plugins are often sophisticated so maybe ZSD will be used, and (z) flag = solves the effort-problem, even for Bash =E2=80=93 just tried to run ZSD = on an old 550-line Bash script with 9 functions (it implements youtube-dl= queue, for slow networks), and it worked. -- =20 Sebastian Gniazdowski psprint /at/ zdharma.org