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.3 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED,UNPARSEABLE_RELAY autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 16106 invoked from network); 16 Feb 2021 18:21:54 -0000 Received: from zero.zsh.org (2a02:898:31:0:48:4558:7a:7368) by inbox.vuxu.org with ESMTPUTF8; 16 Feb 2021 18:21:54 -0000 ARC-Seal: i=1; cv=none; a=rsa-sha256; d=zsh.org; s=rsa-20200801; t=1613499714; b=W72j8ij5PqZozCGZB1xICyH40uVWNBHOyx5KWwnQhgjJ9W0O6CgRGRC2N83w6kTPL3p2mNkSrG h0hXmLSfGmx3M+jsrhLx8j+9xTzdrC7NvAn/BN9n7eyLmWaZ6Ujv1NkSdB1sf8fZxxf0JRVTNv LIEAiPi00I/wFhXPPbyWNruNVki/rW8CpqpwWQbUFRpBVZBZ22M6yUq4mKoP2YlWrqVPxXIqtp coLK8HCPaEKEPHhI5TCVmfBXu9CjzhHupbusgXz849DulVcw3k+GnZFzk1Uyn9bTXY8h0CI3gG n2yt14K4sFfkk4K8BDQfI/Qdbrrytdl36rtn71+mAWbcYQ==; ARC-Authentication-Results: i=1; zsh.org; iprev=pass (relay9-d.mail.gandi.net) smtp.remote-ip=217.70.183.199; dmarc=none header.from=chazelas.org; arc=none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed; d=zsh.org; s=rsa-20200801; t=1613499714; bh=I4jsNA9a3DPaN8wJMCbTBNNqJUiXpifJ08xFPfAVISc=; h=List-Archive:List-Owner:List-Post:List-Unsubscribe:List-Subscribe:List-Help: List-Id:Sender:In-Reply-To:Content-Transfer-Encoding:Content-Type: MIME-Version:References:Message-ID:Subject:Cc:To:From:Date:DKIM-Signature; b=QZVVr99t8j6SFzSEMt05lE5MefQm0ng0C2WsVqBdHPcyUNkRfu8r6QFHCasOGP1Yl27nlfHsQ+ 3In/dlQVqNU1JqYxiifOfNPX4uP9UleA8HB86+kCJjRPF7tRwbfl0BrmopderJh7UNGEkGA/ql S2CEMD5ozCAlDXEAMW9S67mSItSZTFzZgGDnQEPI16nThp6df1GhthLt99Ezd4UGTODGpMTADQ IHVlCfUADPxqIBT9GkQ10uagJitAZ60nHSaUjrxZTk1eSMTc1J2sWAqwDDjQ24D1UVLw47uQuv 8ZRWgt42qXasLIvhxOPSPwxmHtDW/++GiM7lILaULl1ESQ==; 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:In-Reply-To:Content-Transfer-Encoding :Content-Type:MIME-Version:References:Message-ID:Subject:Cc:To:From:Date: Reply-To:Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender :Resent-To:Resent-Cc:Resent-Message-ID; bh=1Z96eS7cb+myZ7W2hYhqqJuget4ityrKEX+qaQW0hRU=; b=Tgm7ekQqdvgB+m/RlPqRBy6Uee 2C3AsRp3dodNJ+TWMfa0u4QxvHNeaC86+iVk/0gxKKYZMbDM12dSjHOE9VXIRsI8eOb5EBX00Oaqu c0OE4d6jdYvaE5CiqyHAaOCwI2brroLCfTzxSjjHrs0EyYoG29FnzyGXJQ0fl9qnCMLayvo0REs4J WlLelOMU4SH5V7rL1iPBZMBnrV6Q/rh6+C65QibXGtMHsKIbw4scHk1SJW3VI3nsmzz9Q1M/ByqBX aIycjA7GIdWx+BN7phj84dzJNmqlXi4fPFwIinpSpDk67KEurQzY3XthR9wMTnz0okxXgGioQl8NG bmEHbUOQ==; Received: from authenticated user by zero.zsh.org with local id 1lC4yv-0007xe-AM; Tue, 16 Feb 2021 18:21:53 +0000 Authentication-Results: zsh.org; iprev=pass (relay9-d.mail.gandi.net) smtp.remote-ip=217.70.183.199; dmarc=none header.from=chazelas.org; arc=none Received: from relay9-d.mail.gandi.net ([217.70.183.199]:48891) by zero.zsh.org with esmtps (TLS1.2:ECDHE-RSA-AES256-GCM-SHA384:256) id 1lC4yd-0007oL-Up; Tue, 16 Feb 2021 18:21:36 +0000 X-Originating-IP: 5.71.197.169 Received: from chazelas.org (0547c5a9.skybroadband.com [5.71.197.169]) (Authenticated sender: stephane@chazelas.org) by relay9-d.mail.gandi.net (Postfix) with ESMTPSA id B5A6AFF805; Tue, 16 Feb 2021 18:21:31 +0000 (UTC) Date: Tue, 16 Feb 2021 18:21:31 +0000 From: Stephane Chazelas To: Juergen Christoffel Cc: Bart Schaefer , Zsh hackers list Subject: pod documentation in zsh scripts (Was: Block comments ala Ray) Message-ID: <20210216182131.xcmynfwgobuh3wlt@chazelas.org> Mail-Followup-To: Juergen Christoffel , Bart Schaefer , Zsh hackers list References: <20210216153049.GA8000@unser.net> MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <20210216153049.GA8000@unser.net> X-Seq: 48071 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: Archived-At: 2021-02-16 16:30:49 +0100, Juergen Christoffel: [...] > That said, wouldn't it be possible to augment the comment parsing to use > something like perl's "plain old documentation" (pod) meachnism, e.g. [...] > P.S. Even the use of the here document for block comments look less > horrible to me, because it's easily recognized when looking at a script. [...] As discussed earlier in this thread, here docs can already be (ab)used to add pod documentation to zsh scripts. An example one could look like: #! /bin/zsh - for a (pod head{1..4} over item back begin end for encoding) aliases[=$a]=":||:<<'=cut' #" =encoding utf8 =head1 NAME mytool - blah =head1 SYNOPSIS B [B<-f>] [B<-h>] [B<-o> I]... =head1 DESCRIPTION B does cool stuff =head1 OPTIONS =over =cut flag=false opt=() while getopts hfo: o; do case $o in (f) flag=true =item B<-f> turns a flag on =cut ;;(o) opt+=("$OPTARG") =item B<-o> I to pass some optional value =cut ;;(h) LESS=${LESS}RFX exec perldoc -oterm $0:P =item B<-h> show this manual. =back =cut ;;(*) exit 1 esac done =head1 AUTHOR Stéphane =cut