[Replying to multiple posts in the same email.]

On Wed, Mar 6, 2019 at 4:17 PM Alex Shinn <xxxxxx@gmail.com> wrote:
> How about Scribble?

On Wed, Mar 6, 2019 at 4:32 PM Arthur A. Gleckler <xxxxxx@speechcode.com> wrote:
> While Scribble, LaTeX, and other tools have their merits as source formats, switching to them requires an enormous commitment that I'm just not willing to make.  HTML is a lingua franca that is well established and for which there are countless good tools, and while it's not as beautiful as s-expressions, and it gives authors lots of flexibility about which tools they use to generate it.

Besides Arthur's point, the other issue with Scribble is that it is
very Scheme centric and "exotic".  Many smaller Scheme implementations
wouldn't be able to come up with a Scribble implementation right away.

Therefore, for the goal of allowing other Schemes to incorporate
SRFI's in their documentation, Scribble (like LaTeX and many other
"complex" formats) I think it's too much.

I think that for practical purposes (X)HTML is the best compromise.

On Wed, Mar 6, 2019 at 4:22 PM Lassi Kortela <xxxxxx@lassi.io> wrote:
>  > * for actual signatures I think an S-expression based description is
>  > better (however see the other paragraph where I note that perhaps this
>  > is too much for SRFI's);  for example:
>
> This is obviously far superior to any HTML-based approach, but would
> have to be maintained in a separate file from the SRFI HTML.

I agree that this "signature" part (or better said formalization of
the SRFI procedures and syntaxes) should be put "aside" the actual
SRFI document.

(I do think it could be part of the (X)HTML appendix, but this is just
a detail.)

On Wed, Mar 6, 2019 at 4:22 PM Lassi Kortela <xxxxxx@lassi.io> wrote:
> I think our main point of disagreement is how much worse it is to have
> a separate file. I'm willing to live with clumsy HTML markup if we can
> have only one file per SRFI. You're willing to live with two files per
> SRFI if we can have great metadata syntax (S-expr or JSON). Correct?

My disagreement is not about the two "files".  As said above I agree
that the "signature" part is too "advanced" at this moment, and we
should just let it aside.

However my disagreement with your proposed HTML classes is that they
are "too-much" by trying to "formalize" that "signature".  In fact I
say that the HTML format should be concerned only with minor
augmentations meant to ease indexing and back-referencing.  Anything
more advanced than this (i.e. arguments, return values, etc.) should
be out-of-the scope and moved to a more structured document.

Again one of the main "features" of the proposed (X)HTML format is
easy transformation and ingestion into other documentations (not
necessarily HTML).

On Wed, Mar 6, 2019 at 4:22 PM Lassi Kortela <xxxxxx@lassi.io> wrote:
> Could we get everyone's opinion on this issue, as it may be the
> biggest detriment to forming a consensus? Who would rather have
> somewhat clumsier markup but require only a single HTML file, and who
> would rather have separate HTML and metadata files if it means the
> HTML markup can be somewhat cleaner?

My vote is clear:  Simpler (X)HTML format just indexing and back-referencing.
(This could include the name, description and perhaps examples.)

Another proposal should cover the heavier syntax meta-data.

On Wed, Mar 6, 2019 at 4:22 PM Lassi Kortela <xxxxxx@lassi.io> wrote:
> I think we all agree HTML classes are not an ideal way to represent
> information. But from my point of view the other options are even
> worse :) That's why I've been advocating classes. If I've understood
> correctly, Arthur and Per have a similar viewpoint.
>
> [...]
>
> But basically, you already have to write the procedure names and
> argument names in the HTML, and they are often written in a special
> font. Hence there is already a tag around them. If the markup is e.g.:

Don't get me wrong:  I am for these "classes".  However I am against
trying to use them to transform HTML into S-expressions.

It might not be hard to gradually augment the HTML to look like
exported HTML, however the outcome would be an awful HTML file.
Moreover not much accurate data would be extracted from that format.

On Wed, Mar 6, 2019 at 4:22 PM Lassi Kortela <xxxxxx@lassi.io> wrote:
> I don't think there is any way to avoid verbosity because no matter
> what HTML-based approach we choose, we have to write <foo class="bar">
> all over the place. Personally, I would argue that HTML is already
> quite verbose even without any metadata. Hence elegant HTML is
> something of a lost cause to begin with.

Not necessarily.  HTML allows one to use arbitrary tags (both for
elements and for attributes).  Thus instead of `<span
class="def-proc">make-array</span>` one could just write
`<s-def-proc>make-array</s-def-proc>` or alternatively `<span
s="def-proc">maker-array</span>` and besides a minor warning from the
W3C validator would be fine.

On Wed, Mar 6, 2019 at 4:22 PM Lassi Kortela <xxxxxx@lassi.io> wrote:
> Invisible tags can maybe be avoided with creative uses of
> data/id/rel/rev attributes, but that probably creates even more
> problems. Many tags can be made visible, but attributes are always
> invisible...

The problem with the "creative uses of data/id/rel/rev attributes" is
that outside the ones that propose and develop this format, the others
won't know how to use it, because these attributes are low-level HTML
ones, mainly created for technical purposes, thus not for human
authors.

On Wed, Mar 6, 2019 at 4:39 PM Arthur A. Gleckler <xxxxxx@speechcode.com> wrote:
> It should be possible to make this really lightweight.

Exactly.  That is why I'm saying that a minimal "best practices"
(X)HTML with only a few elements (headers, paragraphs, lists, code and
pre) and a few attributes (perhaps classes) should be enough to write
in (X)HTML, but at the same time display with a modern CSS, and if
needed translated to other markup languages like Markdown.

On Wed, Mar 6, 2019 at 6:39 AM Arthur A. Gleckler <xxxxxx@speechcode.com> wrote:
>
> Here's a slightly better example that includes multiple optional arguments as well as example CSS:
>
> .def::before {
>   content: "Procedure: ";
> }

I don't think inserting text from CSS would be a good idea, since
while editing the text the author can't see what it would actually be
read like.  Moreover this would break the attempt to export the HTML
to other formats.

Ciprian.