From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.io/gmane.text.pandoc/25839 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: =?utf-8?Q?Gabriel_N=C3=BCtzi?= Newsgroups: gmane.text.pandoc Subject: Re: Self-documenting Lua modules Date: Wed, 12 Aug 2020 00:06:22 +0200 Message-ID: <22D9BE00-5CC2-4AD6-B146-7F5CFA014E19@gmail.com> References: <87h7t9ilp2.fsf@zeitkraut.de> Reply-To: pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org Mime-Version: 1.0 (Mac OS X Mail 12.4 \(3445.104.15\)) Content-Type: multipart/alternative; boundary="Apple-Mail=_EDCCC62B-F680-4C4C-85E7-5600EAA34516" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="39908"; mail-complaints-to="usenet@ciao.gmane.io" To: pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org Original-X-From: pandoc-discuss+bncBDRZVNGQEQIODLGM7ECRUBG4YND6O-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org Wed Aug 12 00:06:27 2020 Return-path: Envelope-to: gtp-pandoc-discuss@m.gmane-mx.org Original-Received: from mail-lf1-f57.google.com ([209.85.167.57]) by ciao.gmane.io with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1k5cPb-000AIh-JZ for gtp-pandoc-discuss@m.gmane-mx.org; Wed, 12 Aug 2020 00:06:27 +0200 Original-Received: by mail-lf1-f57.google.com with SMTP id w138sf4488948lff.22 for ; Tue, 11 Aug 2020 15:06:27 -0700 (PDT) ARC-Seal: i=2; a=rsa-sha256; t=1597183587; cv=pass; d=google.com; s=arc-20160816; b=x9rSUIn1nEj3+4sgucDWyxpTWvTkPYZeQhct1TcE5lR2AIiFRdkpsUt8l5JyC9zLcD 73kh2UK+mnIc0RmFqo+AhQRBlPcvY4N7J+6+0cAfOPQPmRBT5pjhHvGV4vL+EqD18wUT C0kUFEGzKsUtIvNHWFQIGVudIPzYEDxlnwL8AWAaLgAYScgZtKU+PeXdsThuGkBuFB+J QG6YGn6Zp5JwRRPlHHBrcEenbF0jAuI8bz0UzcAgfpOb2DBOG3o9aUWeTYnxQCRpkfH8 IwYrM9ABDfLDxSbCOFPaUDR8FCbDvsHttDDKv4rCQkzht6RJ6BAk2RbObCEZRsp2EDtH QKTw== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-unsubscribe:list-subscribe:list-archive:list-help:list-post :list-id:mailing-list:precedence:reply-to:message-id:in-reply-to:to :references:date:subject:mime-version:from:sender:dkim-signature :dkim-signature; bh=M1qvma4MNA3zDoi4K5le/bmPX1uZaT4o9PZyIzPotFg=; b=Q9oSViPRQ/+Nr2Lcto9ml1t3P5YC1KgMadja7Emn3tM4BWsW0XpNrkPQEKf6giatSd eDZdCLcgbl0252CLjxNGegUdycuqgQD+S1ZL5xswXUA0Z0i6Kd2VwmZdgcg9afDg0k0S cwproG16dX9r2Qp3wIV25qLqQ8y+QJsdTrvZ1j5wauIJgKqiPNXeBvutHj3Ps83CjY+a sRNe8ZcyHpyCTpecopr+SZmWFYwycjIHJDYKabCZLqcdCQ4ItoZuAkZqt4eWolfhEoKO eJMQBcX5MhycQnNCAknmpLuWqcS0WwoK60+3XbLJAuZWJ6SX3WVW2XwvwKYd0XNSUOsB 9iwQ== ARC-Authentication-Results: i=2; gmr-mx.google.com; dkim=pass header.i=@gmail.com header.s=20161025 header.b=GmjBy3I2; spf=pass (google.com: domain of gnuetzi-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org designates 2a00:1450:4864:20::52a as permitted sender) smtp.mailfrom=gnuetzi-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlegroups.com; s=20161025; h=sender:from:mime-version:subject:date:references:to:in-reply-to :message-id:x-original-sender:x-original-authentication-results :reply-to:precedence:mailing-list:list-id:list-post:list-help :list-archive:list-subscribe:list-unsubscribe; bh=M1qvma4MNA3zDoi4K5le/bmPX1uZaT4o9PZyIzPotFg=; b=Ex7zzsWuH7wteMBZ6oYyUVn7fD1XPTY9FUTSZWARo84EQReXJLqTop0dtNwOyklIBX 8jvuOnGwmxBiR4HTzSZyLst47wkaiAjnBuVp36VlRCVCrTO5yusxhAHxcTbBP8c6Tp2v 0SZDNQoCtTTHZSh14jpMFC7ZaVQgXlt78fkUI1Lx8ZUNhGqKa5Ot/nAp8ttHJijusXGe NY1DsH7bPvEn42sqTqqBBxMAKWXY+RJ0J+WFStHZT2H+ICbTk18xQlyIgQz+97VuHB2C lpDm7ukcIh/M8UEYjiVM+C+rc6Eu6q2ImgJ4Edn3CFWnKqvnAbOVCV8NwoC//HsbkaAd bO/Q== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:mime-version:subject:date:references:to:in-reply-to:message-id :x-original-sender:x-original-authentication-results:reply-to :precedence:mailing-list:list-id:list-post:list-help:list-archive :list-subscribe:list-unsubscribe; bh=M1qvma4MNA3zDoi4K5le/bmPX1uZaT4o9PZyIzPotFg=; b=ML3U0oqiJJ0KXnIjtwRpet9x23mrs6zCN6/FrJ5BwEimWHOzpUcLXHgs2osXzB2ld+ 9Ms4sgpHt2gtbcv+pHqYYwmN0Vp1DetyzSJTkJJwEA3Zk5FCNIkNRngqOfwwfh6jTKCr rKiNcn6KIG/vG580xDencbcbqxX7ydQ48MooEWirwNf/yvpWc6GRxHt+cWiXjfQCAvYH CLCKOarHJjwfoq3Ua3smnwwZaBaqNgnQ5KAd23s2r2G+QV8N0finrTg1rgc1D9LyxqCD +NsY4XBA1KIdmZPWTzhoajbUN4mveXkRAgVSHZDwbvyVT3070gvewNLEFktPK5bk//07 uH6w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=sender:x-gm-message-state:from:mime-version:subject:date:references :to:in-reply-to:message-id:x-original-sender :x-original-authentication-results:reply-to:precedence:mailing-list :list-id:x-spam-checked-in-group:list-post:list-help:list-archive :list-subscribe:list-unsubscribe; bh=M1qvma4MNA3zDoi4K5le/bmPX1uZaT4o9PZyIzPotFg=; b=IVFvXWtQ+j+oCBP4AxxUzALlIHGBfngE6eH9eht+garOP9Jwe+FC/ZrJ8t4BskoIRk 5yYkEj/N4O/utXtlir72dLo6+YDnXqPeFW5jGpsPzInhAmRiOoLDXwpV0aEPdQFK2j3C lWnqrHgZXk4LJbdOeyO3X1SzXWSaN+TDQPYDzLq6Oq0uGpHS4ljmlbYRmPeMKelcCiP6 PVGocYfn+zgj65/nhls1H6b9VACJQfuDUfRvYIk6HDE47kLbqpjH6EW5xpoPb06poPmS dP82WiPVu8y+YIMjZJZKhK5i+kQsShpyrmRSfaJDbXB7J04KDFnwCJXGo1nhtQPdetqn VzQQ== Original-Sender: pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org X-Gm-Message-State: AOAM530ChOeU15oeV3d6Iqjw+8R76yqzMNj9oipIH3vx9k8kR/fa7E9m bm5qHvIpSd9UvqHKRhke+vo= X-Google-Smtp-Source: ABdhPJzHueYVd9vEymGLoAO0JpKYLIH8J4twMmtRW0C90lsxkP6/iwv9u//j2EGD4BKGwBEVk4oTCA== X-Received: by 2002:a19:7ec3:: with SMTP id z186mr4077825lfc.3.1597183587081; Tue, 11 Aug 2020 15:06:27 -0700 (PDT) X-BeenThere: pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org Original-Received: by 2002:ac2:4845:: with SMTP id 5ls29687lfy.2.gmail; Tue, 11 Aug 2020 15:06:25 -0700 (PDT) X-Received: by 2002:ac2:5b46:: with SMTP id i6mr4106866lfp.135.1597183584930; Tue, 11 Aug 2020 15:06:24 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1597183584; cv=none; d=google.com; s=arc-20160816; b=pDWnfuVMxKnUuw6Z0R0A7GORCqsy7Yw/X1YIJF0GEO+zJtlK7IJ+KiKOR8uJtxpxQR HT4Qs0OfqgmsMJWMf7B1DC8DkH8rU9yiU0erh4e6n9wZ8zl/zeZCOqiDml2LJ/Uv/qEl 8g/HRslQ5QjmCMd09cJYSHAHyqP3iM7xAYtadetBlh4sVLP4+E8+rPKhLYovNbwCjhau ydenH+ZXLItzMevV+8PC+hsLt+qfvXUB0GGUFjsZlOTqqbcfCZgg6xktirB+GJ9BI7pM GhAIM/LZmGxDWwam/zZ5nW9ugPNyOyJ9f9ng7fsOxQhkv7ArfMtcMtLLYLSfFytniVDo dEsQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=message-id:in-reply-to:to:references:date:subject:mime-version:from :dkim-signature; bh=GD0t2FKvRelg9BHnL0mNSxv9X1+RXwnhK5z/ZmbIs9s=; b=j1tGO2uc+kL8/h7lsrQyONrMrc3c9jC1boYUk2TBSyIrwjioh+oBjRSJsAXwnpf/vL 6oa8dLAQSulv/6ICfGwaefMiRm4GJJIJ9OuZnImFHn6b9LQgk+4W92mvTnzyEP86R1q5 mLJwqypsx7LH+tI55wUQzc/S0x51+X7XUB/2ObZ2MSIR27ddR0L7OcRodKhTLKfFXJv+ +ogBpdPuDyqe/s/4jC3++pxiij4PB6u/GFW6u9RFmweCyUY6Hr1m3oS7tP++HpjJi67W 4/xJNjrYQlX8+7FaMBBjgTiQSx60K5a3jeehzQyJRd87pcYhMGhmGdR7vzIVjKugYbXz p+qg== ARC-Authentication-Results: i=1; gmr-mx.google.com; dkim=pass header.i=@gmail.com header.s=20161025 header.b=GmjBy3I2; spf=pass (google.com: domain of gnuetzi-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org designates 2a00:1450:4864:20::52a as permitted sender) smtp.mailfrom=gnuetzi-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Original-Received: from mail-ed1-x52a.google.com (mail-ed1-x52a.google.com. [2a00:1450:4864:20::52a]) by gmr-mx.google.com with ESMTPS id o13si8091lfc.0.2020.08.11.15.06.24 for (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Tue, 11 Aug 2020 15:06:24 -0700 (PDT) Received-SPF: pass (google.com: domain of gnuetzi-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org designates 2a00:1450:4864:20::52a as permitted sender) client-ip=2a00:1450:4864:20::52a; Original-Received: by mail-ed1-x52a.google.com with SMTP id m20so23462eds.2 for ; Tue, 11 Aug 2020 15:06:24 -0700 (PDT) X-Received: by 2002:a05:6402:305b:: with SMTP id bu27mr28583327edb.300.1597183583987; Tue, 11 Aug 2020 15:06:23 -0700 (PDT) Original-Received: from gabyxs-imac.fritz.box ([109.70.117.49]) by smtp.gmail.com with ESMTPSA id z10sm165085eje.122.2020.08.11.15.06.23 for (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Tue, 11 Aug 2020 15:06:23 -0700 (PDT) In-Reply-To: <87h7t9ilp2.fsf-9EawChwDxG8hFhg+JK9F0w@public.gmane.org> X-Mailer: Apple Mail (2.3445.104.15) X-Original-Sender: gnuetzi-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org X-Original-Authentication-Results: gmr-mx.google.com; dkim=pass header.i=@gmail.com header.s=20161025 header.b=GmjBy3I2; spf=pass (google.com: domain of gnuetzi-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org designates 2a00:1450:4864:20::52a as permitted sender) smtp.mailfrom=gnuetzi-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Precedence: list Mailing-list: list pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org; contact pandoc-discuss+owners-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org List-ID: X-Google-Group-Id: 1007024079513 List-Post: , List-Help: , List-Archive: , List-Unsubscribe: , Xref: news.gmane.io gmane.text.pandoc:25839 Archived-At: --Apple-Mail=_EDCCC62B-F680-4C4C-85E7-5600EAA34516 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="UTF-8" Gabriel N=C3=BCtzi to Albert Krewinkel: This actually looks pretty fancy. I can=E2=80=99t contribute relevant input= , but kindly have some questions: The code=20 -- | See @System.FilePath.takeExtensions@ take_extensions :: HaskellFunction take_extensions =3D toHsFnPrecursor Path.takeExtensions <#> filepathParam =3D#> filepathResult "String of all extensions." #? "Get all extensions." How can a novice (like me ;-)) understand this <#>, =3D#> #?... Is this tak= e_extensions Function some kind of a special =E2=80=9Cthing=E2=80=9D which = can be called, but enables also to collect the doc by doing something else with it? Is this going the way like D. Knuth with its TeX Language? S= elf-documenting code :) Is there no tooling for haskell which extracts the code documentation `=E2= =80=94| =E2=80=A6` etc=E2=80=A6? Just curious? Thanks for putting this path stuff in a separate library, I thought of it m= ight be at the wrong place in th PR :-)=E2=80=A6 Cant wait till we have thi= s in the filter, such that I can adapt the include-files filter to accept = relative includes=E2=80=A6 BR Gabriel > On 11 Aug 2020, at 11:19, Albert Krewinkel w= rote: >=20 > Dear *, >=20 > I'm working on some code to improve Lua bindings and integration > and would appreciate feedback on the approach. >=20 > In a PR discussion on GitHub, jgm describes the problem which I'm > now trying to solve: >=20 >> I'm getting a bit worried about the ongoing maintenance cost of >> shadowing large parts of the pandoc (and related) API with Lua. >> In the present case: if I make further changes to doclayout, >> then this custom Lua code needs to be updated, and so does the >> documentation. However, I'm not sure anything would >> automatically alert us to the need to do these things, which >> raises a danger of breakage as things get out of sync >> (especially if you ever stop being such an active contributor to >> the project). >=20 > Currently, pandoc's Lua documentation and Lua bindings are > entirely separate. The missing documentation for the new table > format recently is an excellent example of the problems we are > facing and highlights the shortcomings of our current method. >=20 > The idea is thus to co-locate documentation and code. Here is a > first prototype, using a potential `paths` module for filepath > handling as an example: > > Explicit typing of function parameters should give better > compile-time guarantees, while keeping documentation close to the > code should reduce the risk of an outdated manual. The > documentation for this module can be generated by running `cabal > run tools/print-docs.hs`. >=20 > If anyone has experience with this kind of approach, can comment > on the code, or wants to share other ideas that could help us make > pandoc's Lua code more robust, then I'd love to hear about it. >=20 > Cheers, > Albert >=20 > -- > Albert Krewinkel > GPG: 8eed e3e2 e8c5 6f18 81fe e836 388d c0b2 1f63 1124 >=20 > --=20 > You received this message because you are subscribed to the Google Groups= "pandoc-discuss" group. > To unsubscribe from this group and stop receiving emails from it, send an= email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org > To view this discussion on the web visit https://groups.google.com/d/msgi= d/pandoc-discuss/87h7t9ilp2.fsf%40zeitkraut.de. --=20 You received this message because you are subscribed to the Google Groups "= pandoc-discuss" group. To unsubscribe from this group and stop receiving emails from it, send an e= mail to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org To view this discussion on the web visit https://groups.google.com/d/msgid/= pandoc-discuss/22D9BE00-5CC2-4AD6-B146-7F5CFA014E19%40gmail.com. --Apple-Mail=_EDCCC62B-F680-4C4C-85E7-5600EAA34516 Content-Transfer-Encoding: quoted-printable Content-Type: text/html; charset="UTF-8" Gabriel N=C3=BCtzi to Albe= rt Krewinkel:

This actu= ally looks pretty fancy. I can=E2=80=99t contribute relevant input, but kin= dly have some questions:

The code 
-- | See @System.FilePath.takeExte=
nsions@
take_extensions :: HaskellFunction
take_extensions =3D toHsFnPrecursor Path.takeExtensions
  <#> filepathParam
  =3D#> filepathResult "String of all extensions."
  #? "Get all extensions."
How can a novice (like me ;-)) understand this <#>, =3D#> #?= ... Is this take_extensions= Function some kind of a special =E2=80=9Cthing=E2=80=9D which can be calle= d, but enables also to collect the doc by doing something
else with it? Is this going the way = like D. Knuth with its TeX Language? Self-documenting code :)
=
Is there no tooling for haskell which extracts the = code documentation `=E2=80=94| =E2=80=A6` etc=E2=80=A6? Just curious?

Thanks for putting this path stuff in a separate library, I thought= of it might be at the wrong place in th PR :-)=E2=80=A6 Cant wait till we = have this in the filter, such that I can adapt the include-files filter to = accept relative includes=E2=80=A6

BR Gabriel


On 11 Aug 2020, at 11:19, Albert Krewinkel <albert+pandoc-9EawChwDxG8hFhg+JK9F0w@public.gmane.org> wrote= :

Dear *,

I'm working on some code to impr= ove Lua bindings and integration
and would appreciate feedbac= k on the approach.

In a PR discussion on GitHu= b, jgm describes the problem which I'm
now trying to solve:
I'm gettin= g a bit worried about the ongoing maintenance cost of
shadowi= ng large parts of the pandoc (and related) API with Lua.
In t= he present case: if I make further changes to doclayout,
then= this custom Lua code needs to be updated, and so does the
do= cumentation. However, I'm not sure anything would
automatical= ly alert us to the need to do these things, which
raises a da= nger of breakage as things get out of sync
(especially if you= ever stop being such an active contributor to
the project).<= br class=3D"">

Currently, pandoc's Lua documenta= tion and Lua bindings are
entirely separate. The missing docu= mentation for the new table
format recently is an excellent e= xample of the problems we are
facing and highlights the short= comings of our current method.

The idea is thu= s to co-locate documentation and code. Here is a
first protot= ype, using a potential `paths` module for filepath
handling a= s an example:
<https://github.com/hslua/hslua-module-paths>=
Explicit typing of function parameters should give bettercompile-time guarantees, while keeping documentation close to t= he
code should reduce the risk of an outdated manual. The
documentation for this module can be generated by running `cabal=
run tools/print-docs.hs`.

If an= yone has experience with this kind of approach, can comment
o= n the code, or wants to share other ideas that could help us make
pandoc's Lua code more robust, then I'd love to hear about it.

Cheers,
Albert

--
Albert Krewinkel
GPG: 8eed e3e2 e8c5 6= f18 81fe  e836 388d c0b2 1f63 1124

-- You received this message because you are subscribed to the Goo= gle Groups "pandoc-discuss" group.
To unsubscribe from this g= roup and stop receiving emails from it, send an email to pandoc-discuss+unsu= bscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org.
To view this discussion on the = web visit https://groups.google.com/d/msgid/pand= oc-discuss/87h7t9ilp2.fsf%40zeitkraut.de.

--
You received this message because you are subscribed to the Google Groups &= quot;pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an e= mail to pand= oc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org.
To view this discussion on the web visit https://groups.google.com/d/msgid/p= andoc-discuss/22D9BE00-5CC2-4AD6-B146-7F5CFA014E19%40gmail.com.
--Apple-Mail=_EDCCC62B-F680-4C4C-85E7-5600EAA34516--