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,T_SCC_BODY_TEXT_LINE, UNPARSEABLE_RELAY autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 10561 invoked from network); 20 Apr 2022 22:43:23 -0000 Received: from zero.zsh.org (2a02:898:31:0:48:4558:7a:7368) by inbox.vuxu.org with ESMTPUTF8; 20 Apr 2022 22:43:23 -0000 ARC-Seal: i=1; cv=none; a=rsa-sha256; d=zsh.org; s=rsa-20210803; t=1650494603; b=hdLgSAvGjgfdSZntcW5rqEqb3W2gHZtXTtZjKjz7R2naVQD7rBZmEPB7fWvpThAKaWPKLwyir+ unr2vmGLqRR9ZI3K9+x/ezC2qpCEEfsW1TkQQLdx8mCrTGiI+KkzhcQbU6yBLeSb+ddlHqA/oq NaDhqeRRKnN6VL3STHLAFeDh73lY1TgFxNTEUql1QN88FbrlQllYSJGcLuc4EJzwpcwG0fRTFe 33Bj6geYDF+d+9j2UZp6zXV9udyYgrvbNVbJAyGA66j8gp+60DSchnv3/sGEdQpc5q9V1iiFAt NzarM3b25WNqQCuYurfqUKMtlv3NPFHZz6iD8LVKaVOxoQ==; ARC-Authentication-Results: i=1; zsh.org; iprev=pass (mail-ej1-f49.google.com) smtp.remote-ip=209.85.218.49; dkim=pass header.d=brasslantern-com.20210112.gappssmtp.com header.s=20210112 header.a=rsa-sha256; dmarc=none header.from=brasslantern.com; arc=none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed; d=zsh.org; s=rsa-20210803; t=1650494603; bh=sC1+jgXUdwLsnBSSWQmoNSS/2B50S59w4leg+/LAKBU=; h=List-Archive:List-Owner:List-Post:List-Unsubscribe:List-Subscribe:List-Help: List-Id:Sender:Content-Type:Cc:To:Subject:Message-ID:Date:From:In-Reply-To: References:MIME-Version:DKIM-Signature:DKIM-Signature; b=Wxy1fdLxoAnqXvo/EqSjvHmvoesMfinRQTjQrNIG8WyO8RdhpeaxwKDJNjBfNDlDdx2E+jRo+6 WanCF8QKrNLN0G2eD69/lxQR9sUVUIA2/RwqX5qCLUrSSbGOucD+5f2XqoYk2y4yvZPvW77srY Ij3MAf85w2/YHUtf2vTz6YYRPccE0KrwC34bTji6V5Z7yid74gTT97eU5L0JxigYnM3lRTIIS9 XvzIfl9FQ89QRCtdIZkH7+BTF6PvLvGIgZ44pnpiUlcj1y2skA9hhg4cM+hJx1umltrasFioyX O36AMqHbUGqxHqO5F4Kyhzb85chqVqH5jHdgRBKp+ClBGQ==; DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=zsh.org; s=rsa-20210803; h=List-Archive:List-Owner:List-Post:List-Unsubscribe: List-Subscribe:List-Help:List-Id:Sender:Content-Type:Cc:To:Subject:Message-ID :Date:From:In-Reply-To:References:MIME-Version:Reply-To: Content-Transfer-Encoding:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID; bh=dcEiCLaenQwWggSH0/WTO89FG0RhHxfhS00T5iBPP3s=; b=HAw6QYxI2AXaZeYbTnF/zlskdE 2sT4bwmoa31fPHEhNdYpuD42M4wWekTH7uRQtKBgE5l9fZ8xYdnu+EfusQ1erqFG1Aje8oLNey/7z WhPVpNkWSmVF7EpZC5LGLjy2UI3yzc4ClejOiz8CJXPGV53lHlOCtdcE8a7Bm0VAPZVl+8b4eW988 p6s1lTc7QUdKbP5PHFlOd6NkNdhrZ2pjzJHaBzDsf4L6SRlZA2xgLIDCVxVd8xDgT1yq+le+vFPVY qTzty8xRYznmBfTBv0EH7q3ugTWqMDpHfM2HwkiPiOfHdr2WXsRbsGMQdZY+0C1HYGuqilJer1wc+ 1dE1P6uA==; Received: from authenticated user by zero.zsh.org with local id 1nhJ2f-000Mu8-UI; Wed, 20 Apr 2022 22:43:22 +0000 Authentication-Results: zsh.org; iprev=pass (mail-ej1-f49.google.com) smtp.remote-ip=209.85.218.49; dkim=pass header.d=brasslantern-com.20210112.gappssmtp.com header.s=20210112 header.a=rsa-sha256; dmarc=none header.from=brasslantern.com; arc=none Received: from mail-ej1-f49.google.com ([209.85.218.49]:45600) by zero.zsh.org with esmtps (TLS1.3:TLS_AES_128_GCM_SHA256:128) id 1nhJ1o-000MES-7L; Wed, 20 Apr 2022 22:42:29 +0000 Received: by mail-ej1-f49.google.com with SMTP id lc2so6370957ejb.12 for ; Wed, 20 Apr 2022 15:42:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=brasslantern-com.20210112.gappssmtp.com; s=20210112; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=dcEiCLaenQwWggSH0/WTO89FG0RhHxfhS00T5iBPP3s=; b=wGCrz7MrKIiTMwPR7UHKfOfBXYmxSjFEzlq0nXJw34QHmf3xeihTl+GIQdoUmm2j5M MJdPVPlA8mNsX0uQICCy+Y5dbT+7J1vSHLz++xkiTFeD9Gvuyv2fEuBbEOyuqKYbd/E1 I9w1Bm1IqhplR0YBl7JhSWe+XYK6TgMrT6OfeN2OTdoGmQ1NqZQgRFwXaCmzM4okU+NK TohJml8AMkx3HflDga3/+T2ZXJObI04yt2GX5URYrZKhb62/tDo0guVVZujGq1sr68pT 0dxmF9uL6zFHd3paubBU+Xt5ofzeHSuxFSzGnh4GnAcEJd0p6UtpJzCc1B3FHSrK49Zr 5lRw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=dcEiCLaenQwWggSH0/WTO89FG0RhHxfhS00T5iBPP3s=; b=WJEbhm+lDtpJp81cSIZJAXQaSaN64vmwNQLYGCD11L0P5Twfu6PfirgCqbovrsLesh FLeFjkACXKb4ZOXu6BbCgCSVDUH+6yVREa/Ic7tTOAbaSdy7XyjvXsIvQsGP05Ooet27 V3nU9Q3G59+mDfzV+rpy69dZ3NIg1ULvmxFrq2+5dIaevaGh543T3GR4oOn/fJ+fg8Vo k9X8jMEnKHPQ4c8a8po+/dTL7HQPXwW2B6NdiC0WaUJxwYF7D88uPBvjoOuRxw/+GWtD zpH3H0MhW7Rz5+qfKiANJAC7YLLdG315TOZ9aba6YtGWtQUZmQuNQE5VX/B+O+KBXc20 8gJA== X-Gm-Message-State: AOAM532QdLpENPoRZn6BiFyiwecJIuO57HQJ5SRGNG45F1pzPXcMHzIc Bpb5wPAnSfZypJEC9oxwroWZnWNqFytnWtA/C2p5yg== X-Google-Smtp-Source: ABdhPJxLVgVYwkiUMqguH6L+3u/PWd65SmHzRRirY9wvdrfdIx4KeItkFlaSq+70Zw1FRjAfXak4euo2CkISE2JDNc4= X-Received: by 2002:a17:906:d10f:b0:6e8:94b6:3631 with SMTP id b15-20020a170906d10f00b006e894b63631mr19728587ejz.576.1650494547547; Wed, 20 Apr 2022 15:42:27 -0700 (PDT) MIME-Version: 1.0 References: In-Reply-To: From: Bart Schaefer Date: Wed, 20 Apr 2022 15:42:15 -0700 Message-ID: Subject: Re: HTML docs and Hyperlinks To: Zach Riggle Cc: Zsh Users Content-Type: text/plain; charset="UTF-8" X-Seq: 27679 Archived-At: X-Loop: zsh-users@zsh.org Errors-To: zsh-users-owner@zsh.org Precedence: list Precedence: bulk Sender: zsh-users-request@zsh.org X-no-archive: yes List-Id: List-Help: List-Subscribe: List-Unsubscribe: List-Post: List-Owner: List-Archive: On Wed, Apr 20, 2022 at 12:41 PM Zach Riggle wrote: > > Is there anybody who'd be willing to mentor me / provide 1-1 assistance for adding this functionality to the Yo templates / Yo arguments? Links in the generated html are created with the noderef(target) macro. They're also automatically generated for menu(target) entries and for the node headings introduced by texinode(this)(next)(prev)(up). The "target" in noderef or menu must be a "this" from a texinode. That is, "this" becomes the anchor name for a fragment and noderef or menu creates a URI referencing that fragment. Similarly next/prev/up become URIs referencing the corresponding fragments. Fragments can also be created with the cindex [concepts index], findex [functions index], kindex [styles/tags], pindex [options], tindex [widgets], or vindex [variables] macros. The URIs pointing to those fragments are automatically created in the corresponding index sections, but they're not reference-able elsewhere in the yodl source documents. It's possible they could be made explicitly linkable by edits to Doc/zman.yo and Doc/ztexi.yo, but my TeX skills are 30 years rusty (the HTML is generated by first creating texi and then post-processing that). How closely the fragment URIs get you to the content they're intended to reference depends on where the writer chose to place the yodl macros and on the versions of the tools that transform the yodl or display the result. For example, older versions of the "info" browser would just jump to the top of the node and then forward-search for the target text, which could take you to the wrong place if the target text appeared elsewhere in the prose. To echo Mikael's question, what do you anticipate to introduce that's not covered by the above? > Separately, would Zsh be willing to accept a post-processing step to the HTML documentation to add things post-hoc? This will likely require some Python libraries being included in the process of building the docs. We've used Perl for such post-processing so far (e.g., Util/helpfiles); I can't speak to whether python is now so ubiquitous that creating a dependency on it would be a non-issue.