[SG10] SD-6 document structure

John Spicer jhs at edg.com
Sun Jul 24 21:24:55 CEST 2016


> On Jul 22, 2016, at 7:59 PM, Nelson, Clark <clark.nelson at intel.com> wrote:
> 
> A year or so ago I mentioned that I thought it would be good idea for SD-6
> to have an index of macro names. I haven't done anything about that yet, but
> I haven't forgotten about it.
> 
> More recently, it seems to me that the document has gotten fairly
> cumbersome. I'm starting to think that it would be helpful if all the
> rationale (including examples) appeared in a separate HTML file from the
> tables, even if it were logically considered part of the same document.

I like the idea of having one document that is essentially just the table and moving the other information into separate document(s).

> 
> It seems to me it might also simplify the maintenance of the index if it
> were in a separate HTML file.
> 
> Does anyone think the idea of splitting up the logical document into
> separate physical documents would be particularly good or bad?
> 
> On a somewhat related topic, as an experiment I have introduced zero-width
> spaces into some of the longer macro names. The idea was to try to get the
> tables presented in a more reasonable width. OTOH, I'm afraid that will
> tend to mess up searches for the macro names. OYAH, if we had an index,
> impacting string searches would be less serious.

I think it would be better to avoid zero-width spaces as that would also impair searching within the document.

> 
> And here's another idea that has occurred to me. Today, in the rationale
> section, I have HTML comments that name a paper's author, and the
> contributor of whatever rationale or example we have. But it might be useful
> to have that information available in the content of the document, so people
> can easily find stuff that's relevant to them (without having to dig into
> the HTML). To make that work would really require CSS tricks -- but the way
> SD-6 is currently published on isocpp.org (i.e. wiki-like markdown), CSS
> can't really be used. So even if we don't want to split up the document, we
> might want to change the way SD-6 is hosted on isocpp.org.

It the explanatory information and rationale were in a separate document we might be able to just have that information always be present in the displayed text.

John.

> 
> Any thoughts?
> 
> Clark
> _______________________________________________
> Features mailing list
> Features at isocpp.open-std.org
> http://www.open-std.org/mailman/listinfo/features



More information about the Features mailing list