Texinfo version of R7RS-small

[Wolfgang Corcoran-Mathe]

Hi all,

There is now a Texinfo version of R7RS-small available at:

https://codeberg.org/Zipheir/r7rs-small-texinfo

A multi-page HTML version generated from the Texinfo is here:

https://www.sigwinch.xyz/scheme/r7rs-small/index.html

Comments and fixes are welcome. Although there are inevitable differences, I've tried to stick to the formatting of the editors' TeX version of the Report as closely as possible.

I'd like to acknowledge Yuval Langer for getting this project going. Hopefully it's useful to someone.

Regards,

Wolf

[Arthur A. Gleckler]

On Sat, Feb 10, 2024 at 10:05 AM Wolfgang Corcoran-Mathe <w...@sigwinch.xyz> wrote:

 

There is now a Texinfo version of R7RS-small available at:

https://codeberg.org/Zipheir/r7rs-small-texinfo

 

This is fantastic!  I've been wanting an Info version of the standard for a long time.  It's much more pleasant to use than a PDF.

Did you end up starting from scratch on the Texinfo, or did you find a source somewhere?

Thanks to you both.

[Per Bothner]

On 2/10/24 10:05, Wolfgang Corcoran-Mathe wrote:
> A multi-page HTML version generated from the Texinfo is here:
>
> https://www.sigwinch.xyz/scheme/r7rs-small/index.html

I suggest using info.js from the texinfo source distribution. That provies
a more functional interface (including info-style keybindings) and has slightly
more modern-looking styling.

For a sample document generated from texinfo, see
https://domterm.org

The info.js javascript is inspired by what I did for Kawa-Scheme, though
that does not (yet) use info.js:
https://www.gnu.org/software/kawa/

The same document converted to using info.js:
http://per.bothner.com/tmp/Kawa-txjs

The same document, but using default the info.js/info.css styling:
http://per.bothner.com/tmp/Kawa-txjs-plain
--
--Per Bothner
p...@bothner.com http://per.bothner.com/

[Per Bothner]

Hm. The latter two sites appear to be a bit buggy - note they're from 2021,
and were only meant for testing. To try out the look-and-feel of info.js, I suggest
using the domterm.org site. Though note that has some custom additions to info.js/info.css,
primarily styling. Of course you're free to adopt what you like of my styling.

[Wolfgang Corcoran-Mathe]

On Saturday, February 10, 2024 at 1:28:12 PM UTC-5 a...@speechcode.com wrote:

Did you end up starting from scratch on the Texinfo, or did you find a source somewhere?

I think Yuval extracted much of the starting text from the PDF, but I'll have to ask him. For the rest, I ran John's errata-fied TeX sources through some ad-hoc scripts and edited the results.

[Dr. Arne Babenhauserheide]

Wolfgang Corcoran-Mathe <w...@sigwinch.xyz> writes:

> There is now a Texinfo version of R7RS-small available at:
>
> https://codeberg.org/Zipheir/r7rs-small-texinfo
>
> A multi-page HTML version generated from the Texinfo is here:
>
> https://www.sigwinch.xyz/scheme/r7rs-small/index.html

That’s awesome — thank you!

I hope it will be provided as info-pages for many distributions, soon,
then lookup of the R7RS API will become much nicer.

> I'd like to acknowledge Yuval Langer for getting this project going. Hopefully it's useful to someone.

Thank you both!

Best wishes,
Arne
--
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

[Wolfgang Corcoran-Mathe]

On Saturday, February 10, 2024 at 1:32:14 PM UTC-5 p...@bothner.com wrote:

I suggest using info.js from the texinfo source distribution. That provies
a more functional interface (including info-style keybindings) and has slightly
more modern-looking styling.

Per, thanks for suggesting this. While I'm very reluctant to add JavaScript (beyond MathJax), I have to admit that the results are quite nice.

Of course, I don't intend to be in charge of how R7RS-small looks in HTML; the version on my site is just a demo. I'm hoping that an HTML version—with whatever bells, whistles, and gongs the community wants—can be hosted at, say, scheme.org at some point.

[Lassi Kortela]

> I hope it will be provided as info-pages for many distributions, soon,
> then lookup of the R7RS API will become much nicer.

Is is possible to submit info pages as an Emacs package to ELPA?

[Lassi Kortela]

> I'm hoping that an HTML version—with whatever bells, whistles, and gongs
> the community wants—can be hosted at, say, scheme.org at some point.

There is currently a HTML version at
https://standards.scheme.org/corrected-r7rs/r7rs.html. It's generated
from the unmodified official TeX sources using
https://github.com/ds26gte/tex2page.

IMHO it's fine to host two different HTML renditions of the same
standard so everyone can use what they prefer. Since the site is
supposed to be a neutral representative of the Scheme community, it's
best to err on the side of more choice. I haven't asked others.

In case you do release tarballs (with a version number or a date), they
can also be added to https://files.scheme.org/.

I've been hoping for an "RnRS gardeners" project that would do technical
maintenance, polishing, and tooling on the reports (while staying
politically neutral about the contents of the reports). But the round
tuits haven't been found yet.

[Per Bothner]

On 2/10/24 11:07, Wolfgang Corcoran-Mathe wrote:
> Per, thanks for suggesting this. While I'm very reluctant to add JavaScript (beyond MathJax), I have to admit that the results are quite nice.

A goal of info.js is that websites using it should degrade nicely. I.e. work
as well as the plain-HTML version if JavaScript is unavailable or disabled.
To the extent that isn't the case, I would consider it a fixable bug.

Given that, I see no reason to not include a modest amount of JavaScript.
Unless you consider it a feature driving away non-insiders with limited functionality
and old-fashioned appearance ...

[Arthur A. Gleckler]

I just noticed the new r7rs.org, which Daphne has been working on through a Codelab repo.  That would also be an excellent place to host an HTML version.

[Arthur A. Gleckler]

On Sat, Feb 10, 2024 at 11:30 AM Arthur A. Gleckler <a...@speechcode.com> wrote:

I just noticed the new r7rs.org, which Daphne has been working on through a Codelab repo.  That would also be an excellent place to host an HTML version.

P.S.: www.r7rs.org was still pointing at the old host, so I've changed it to point to the same host as r7rs.org.

[Yuval Langer]

What I did was to copy and paste each chapter of:

https://standards.scheme.org/corrected-r7rs/r7rs.html

as it appears verbatim in the GNU Emacs's eww browser.

It seemed like the best looking rendition out of:

- `for i in *.html; do pandoc --from html --to plain $i > "$(basename -s .html $i)".txt; done`,
- `pdftotext r7rs.pdf r7rs.pdf`,

- or whatever else I've tried but now forgot…

[Wolfgang Corcoran-Mathe]

On Saturday, February 10, 2024 at 2:22:30 PM UTC-5 Lassi Kortela wrote:

There is currently a HTML version at
https://standards.scheme.org/corrected-r7rs/r7rs.html. It's generated
from the unmodified official TeX sources using
https://github.com/ds26gte/tex2page.

Thanks! I didn't know that existed. I guess I missed the "unofficial" links on the Standards page.

 

IMHO it's fine to host two different HTML renditions of the same
standard so everyone can use what they prefer. Since the site is
supposed to be a neutral representative of the Scheme community, it's
best to err on the side of more choice. I haven't asked others.

If there's already an HTML version then it's not particularly important. The makeinfo-generated text seems to be a little prettier that what tex2page produces, in my biased-by-hours-of-work opinion.

 

In case you do release tarballs (with a version number or a date), they
can also be added to https://files.scheme.org/.

Will do!

[Alex Shinn]

Thank you Wolfgang, this is fantastic!

--

Alex

--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/a097d281-75ce-44fc-b91c-1706795ea0e7n%40googlegroups.com.

[Vincent Manis (he/him)]

This is excellent work, and I commend Wolfgang for it.

I am agnostic about the markup language for the final report, other than
that it should permit the straightforward production of PDF, EPUB, and
HTML versions, as well as some sort of XML thingy (I believe that's the
technical word) that can be used in a hyperspec. TeXinfo certainly fits
some of the bill, as  do LaTeXML and Docbook. The less work we have to
do to make this happen, the better.

I do think that we need to make a binding decision on this pronto. --
vincent

[Dr. Arne Babenhauserheide]

"Vincent Manis (he/him)" <vman...@gmail.com> writes:
> I do think that we need to make a binding decision on this pronto. --

I think that decisions depends on whether we have someone who does the
work reliably — and less on the format itself.

I personally would vote for org-mode, because it can export cleanly to
all the different formats, but as long as there’s no one who would
actually do the work (and writing a report is work, a lot of work,
regardless of the markup), I would abstain from limiting them — except
for requiring that the source format should be a free format and
editable with Free Software.

Best wishes,
Arne
--
This morning I gave a valentine's present to my wife.
This evening I give a valentine’s cheer to the code that runs my life.
I♡FS

[Wolfgang Corcoran-Mathe]

On Wednesday, February 14, 2024 at 1:07:22 PM UTC-5 vman...@gmail.com wrote:

This is excellent work, and I commend Wolfgang for it.

Thanks for the kind words.

 

I am agnostic about the markup language for the final report, other than
that it should permit the straightforward production of PDF, EPUB, and
HTML versions, as well as some sort of XML thingy (I believe that's the
technical word) that can be used in a hyperspec. TeXinfo certainly fits
some of the bill, as  do LaTeXML and Docbook.

 As you'll see if you generate a PDF from the Texinfo sources, the result is so-so; certainly it's nowhere near the quality of the "official" PDF.

I haven't looked at the DocBook or EPUB outputs yet, but I expect them to be equally rough. This is one of the general problems with the "one markup language, many output formats" approach: the quality of the output can vary dramatically, depending on format.

Another problem is that a generalized-output markup language only supports the intersection of features supported by the output formats. Unicode seems to be a serious sticking point here, at least when using the Unicode-ignorant TeX or LaTeX for output. I am not a Texinfo sage, but I'd say the language really shows its age here. (Some characters are canonically provided by math mode (e.g. @math{\lambda}), but this only works for output formats that use TeX. A few others have Texinfo macros, and the rest have to be hacked in with @U{...} macros. (But wait, there's more: @U{} insertions disappear in TeX output.)) If any markup language *is* officially adopted, I hope it's one with better Unicode support.

Like Arne, I don't see any reason for a "binding decision" here. I'd be happy to see experiments with other markup languages. Also, there has been a glut of "lightweight" markup languages in the past decade, and I wonder how much staying power any particular Flavor of the Week will have.

Wolf

[Vincent Manis (he/him)]

On 2024-02-14 12:18, 'Dr. Arne Babenhauserheide' via scheme-reports-wg2 wrote, responding to me:

> I do think that we need to make a binding decision on this pronto. --

I think that decisions depends on whether we have someone who does work reliably — and less on the format itself.

Well, that would be me, I agreed to chair the publications committee

I personally would vote for org-mode, because it can export cleanly to
all the different formats, but as long as there’s no one who would
actually do the work (and writing a report is work, a lot of work,
regardless of the markup), I would abstain from limiting them — except
for requiring that the source format should be a free format and
editable with Free Software.

We can add org-mode to the list of possible formats. Agree that it should  be in a plain text format and not depend on any proprietary software. -- vincent

[Dr. Arne Babenhauserheide]

Wolfgang Corcoran-Mathe <w...@sigwinch.xyz> writes:

> On Wednesday, February 14, 2024 at 1:07:22 PM UTC-5 vman...@gmail.com wrote:
> As you'll see if you generate a PDF from the Texinfo sources, the result is so-so; certainly it's nowhere near the quality of the "official" PDF.
> I haven't looked at the DocBook or EPUB outputs yet, but I expect them to be equally rough. This is one of the general problems with the "one
> markup language, many output formats" approach: the quality of the output can vary dramatically, depending on format.

> Another problem is that a generalized-output markup language only supports the intersection of features supported by the output formats.

This is one of the reasons why I suggest org-mode: it is an intersection
of the different formats, but at least for LaTeX and HTML it allows for
all the polishing in output formats via output-specific tweaks. I’ve
been publishing from org-mode to HTML and PDF (book) for more than half
a decade now, and while I did accumulate quite a few tweaks, it works
really well.

> Unicode seems to be a serious sticking point here, at least when using the Unicode-ignorant TeX or LaTeX for output.

While for HTML this just works, it is one of the things I’m retrofitting
in LaTeX->PDF output: I re-use the uniinput package from neo-layout.org
https://git.neo-layout.org/neo/latex-unicode-extras/src/branch/master/Standard-LaTeX
and added some characters on top to be able to write unicode directly:
https://hg.sr.ht/~arnebab/ews/browse/Hauptdokument/ews30/basesetup.tex#L8

(for my website — also from org-mode — the list of added characters is longer)

[Emmanuel Medernach]

Thanks a lot, this is a great contribution !

Best regards,

Emmanuel Medernach

[Lassi Kortela]

On 2024-02-10 21.56, Wolfgang Corcoran-Mathe wrote:

There is currently a HTML version at
https://standards.scheme.org/corrected-r7rs/r7rs.html. It's generated
from the unmodified official TeX sources using
https://github.com/ds26gte/tex2page.

Thanks! I didn't know that existed. I guess I missed the "unofficial" links on the Standards page.

Yes, those are unfortunate.

We had a discussion long ago (I forget where) about official and unofficial copies of RnRS. The consensus among people who have been close to the standardization process was that every copy where the text has been changed should be regarded as unofficial (even if it's just errata corrections from editors of the standards).

The reasoning is that an RnRS edition is a lot of work, and the people involved should have the guarantee that they can forget about the standard once it's shipped and move on to other things. Confident that their work won't be mangled or misrepresented by people who come later.

So although the "unofficial" copies at https://standards.scheme.org/ contain no changes apart from errata corrections, we still have to call them that and advertise the official versions separately.

It would be good if this situation was explained on the web page somehow. But adding words to a web page is often as likely to add confusion as to reduce it.

If there's already an HTML version then it's not particularly important. The makeinfo-generated text seems to be a little prettier that what tex2page produces, in my biased-by-hours-of-work opinion.

I have no opinion, other than that it would be nice to make it easy to find both versions.