search

pre-srfi / template

Template for SRFI specifications
2 stars 0 forks source link

Add org-mode converter #5

Closed a2379 closed 6 months ago

a2379 commented 6 months ago

Add Gauche scripts to convert org-mode files into a SRFI documents.

I didn't know about https://github.com/scheme-requests-for-implementation/srfi-common until just now. There is some similar code here.

a2379 commented 6 months ago

I think the srfi command can be advertised better. I have been writing SRFIs in HTML and it has been painful to do everything by hand. The srfi-common repo has a lot of files, some are for the editor, some for users. It is difficult to tell what is relevant.

The paragraph on srfi.schemers.org does not mention that the srfi command can be used to generate SRFIs. And the "eighty subcommands" part sounds intimidating to me, and makes me reluctant to try it out.

Also, I think the srfi command is important enough to justify having its own repo.

lassik commented 6 months ago

Thank you. Good feedback. I agree with most of it.

Also, I think the srfi command is important enough to justify having its own repo.

As the SRFI Editor, @arthurgleckler should decide how the repos are laid out.

a2379 commented 6 months ago

@arthurgleckler Sorry about that, this PR is mostly superseded by this one: https://github.com/scheme-requests-for-implementation/srfi-common/pull/73

Closing.

arthurgleckler commented 6 months ago

I think the srfi command can be advertised better. I have been writing SRFIs in HTML and it has been painful to do everything by hand. The srfi-common repo has a lot of files, some are for the editor, some for users. It is difficult to tell what is relevant.

The srfi command isn't for generating the HTML document. Mostly it's tools for the editor. If you run srfi commands, you'll see documentation for the complete list.

The paragraph on srfi.schemers.org does not mention that the srfi command can be used to generate SRFIs. And the "eighty subcommands" part sounds intimidating to me, and makes me reluctant to try it out.

It doesn't generate the primary SRFI documents — just index.html, README.org, the home page, and other documents that I, the editor, maintain.

Also, I think the srfi command is important enough to justify having its own repo.

It's mostly for me, so I keep it with all the other tools.

arthurgleckler commented 6 months ago

To be clear, there are definitely parts of the srfi command that are useful to authors and users of SRFIs. Just run srfi commands to see. In particular, you can use it as a kind of API for getting metadata about SRFIs.

a2379 commented 6 months ago

I'm unclear on where the line is drawn between this template and the SRFI tools, in terms of what is the author's responsibility to generate, and the editor's. Once a SRFI author generates an unformatted HTML document using pandoc, is the expectation that you handle the rest?

I think tasks like copying the abstract to index.html can be automated. That's why I tried to close the loop with this PR: https://github.com/scheme-requests-for-implementation/srfi-common/pull/73

The generate-all command takes the unformatted HTML from pandoc, along with the metadata in a template.scm file, and produces everything, so the editor just needs to add the draft dates and LICENSE files. But maybe it should not be a part of the srfi tool. I don't know.

lassik commented 6 months ago

To be clear, there are definitely parts of the srfi command that are useful to authors and users of SRFIs.

Many, perhaps most, commands are equally useful to readers and writers of SRFIs. I use them all the time.

These could certainly be more discoverable.

arthurgleckler commented 6 months ago

On Sun, May 26, 2024 at 9:33 PM Antero Mejr @.***> wrote:

I'm unclear on where the line is drawn between this template and the SRFI tools, in terms of what is the author's responsibility to generate, and the editor's. Once a SRFI author generates an unformatted HTML document using pandoc, is the expectation that you handle the rest?

Yes, that's exactly right. The author sends the editor HTML in the format defined by the template, leaving the Status section empty. The author also provides a sample implementation and tests. The editor takes it from there. An author can maintain document sources in another markup language as long as the editor receives HTML. In fact, it's okay to send the editor the source markup, too, as long as the author takes care of the conversion. Bradley Lucier, for example, has his own custom markup language that is written in S-expressions. You can see that in SRFI 231 https://github.com/scheme-requests-for-implementation/srfi-231. Everything is included in the repo.

I think tasks like copying the abstract to index.html can be automated. That's why I tried to close the loop with this PR: scheme-requests-for-implementation/srfi-common#73 https://github.com/scheme-requests-for-implementation/srfi-common/pull/73

That's already done, to some degree. I extract the abstract manually and place a copy in srfi-common/admin/abstracts/ https://github.com/scheme-requests-for-implementation/srfi-common/tree/master/admin/abstracts. The part that isn't automated is that I convert any URIs that appear in the abstract into absolute URIs instead of relative ones. But once that is done, the srfi generate-common and srfi generate-srfi number commands take care of copying the abstract and placing it on the home page, on the Github landing page, and on the document's landing page on srfi.schemers.org .

The generate-all command takes the unformatted HTML from pandoc, along with the metadata in a template.scm file, and produces everything, so the editor just needs to add the draft dates and LICENSE files. But maybe it should not be a part of the srfi tool. I don't know.

As long as the generated HTML file follows the template, I'm happy. Whatever we can do to make authors' lives easier is great. I want to encourage more contributions by more people.

arthurgleckler commented 6 months ago

On Mon, May 27, 2024 at 1:37 AM lassik @.***> wrote:

Many, perhaps most, commands are equally useful to readers and writers of SRFIs. I use them all the time.

Yes, sorry. I have an editor-centric point of view, as you can imagine, and overstated how much of the srfi command is for the editors.

I want to thank Lassi for the enormous amount of effort he put into creating the command in the first place, and to making it generally useful.

I'll review your change list again. Thanks for the contribution.

Message ID: @.***>