Split the spec into two

Hey!

It just came to me that the specification for gemini is actually two
specifications intermixed, making it hard to work on only one of the two
components.

I propose to split the specification into either two documents or a
single document with a clear separation between text/gemini and the
gemini protocol.

This shouldn't change anything semantic-wise, but makes working with the
specifications easier as i don't have to skip-read over all text/gemini
stuff when writing the protocol implementation itself and vice-versa.

If that's already planned for one day: Cool, looking forward to that!
If not: Please consider to separate these two parts, even if they are
pretty close related

Regards
- xq

+1

??????? Original Message ???????
On Monday 25 May 2020 13:54, Felix Quei?ner <felix at masterq32.de> wrote:

> Hey!
>
> It just came to me that the specification for gemini is actually two
> specifications intermixed, making it hard to work on only one of the two
> components.
>
> I propose to split the specification into either two documents or a
> single document with a clear separation between text/gemini and the
> gemini protocol.
>
> This shouldn't change anything semantic-wise, but makes working with the
> specifications easier as i don't have to skip-read over all text/gemini
> stuff when writing the protocol implementation itself and vice-versa.
>
> If that's already planned for one day: Cool, looking forward to that!
> If not: Please consider to separate these two parts, even if they are
> pretty close related
>
> Regards
>
> -   xq

On Mon, May 25, 2020 at 01:54:55PM +0200, Felix Quei?ner wrote:
 
> I propose to split the specification into either two documents or a
> single document with a clear separation between text/gemini and the
> gemini protocol.

Yeah, this makes sense.  I hadn't really thought about it, but the
text/gemini spec is kind of smack bang in the middle of the other stuff.

I still think it's a good idea to have everything in one place, but some
rearrangement would not hurt.  I will try to do this tonight.

Cheers,
Solderpunk

> Yeah, this makes sense.  I hadn't really thought about it, but the
> text/gemini spec is kind of smack bang in the middle of the other stuff.
Yeah, it's not always obvious when working a long time on some stuff.
All relevant information is there, but there is stuff added and removed
and one misses the bigger picture sometimes.

> I still think it's a good idea to have everything in one place, but some
> rearrangement would not hurt.  I will try to do this tonight.
Nice, thanks!

Regards
- xq

On Tue, May 26, 2020 at 10:12:26PM +0200, Felix Quei?ner wrote:
 
> > I still think it's a good idea to have everything in one place, but some
> > rearrangement would not hurt.  I will try to do this tonight.
> Nice, thanks!

I just made this change, moving the definition of text/gemini into its
own section at the end of the spec (but before the appendix listing all
status codes), so that all of the protocol stuff is contiguous.

While I was at it, I fixed the ridiculous section numbering scheme.
Literally everything was a subsection of a single top-level section!
Talk about nuts.  So most things that were 1.x.y.z became just x.y.z.
All the text/gemini stuff got moved to its own dedicated section 5, so
the deepest level of nesting is also now one level less than it was
before.

This is a big overall improvement in readability and citeability.
Thanks a lot for suggesting it.

Cheers,
Solderpunk

> This is a big overall improvement in readability and citeability.
> Thanks a lot for suggesting it.

This IS a big improvement!

A small additional idea - would you be open to hosting a `text/gemini`
version? I can definitely see the merit of the `text/plain` version,
for maximum ease of distribution, so maybe this is just asking for
trouble to host two versions, but I do feel at this point in Gemini,
most folks are probably consuming the Gemini spec in a Gemini browser,
within which readability would be substantially enhanced by even just
the addition of a bit of the usual client header line handling (would
you look at that, Gemini supports three levels of it, and now we only
*have* three levels of it in the spec :).

On Tue, May 26, 2020 at 05:18:34PM -0400, Natalie Pendragon wrote:
 
> A small additional idea - would you be open to hosting a `text/gemini`
> version? I can definitely see the merit of the `text/plain` version,
> for maximum ease of distribution, so maybe this is just asking for
> trouble to host two versions, but I do feel at this point in Gemini,
> most folks are probably consuming the Gemini spec in a Gemini browser,
> within which readability would be substantially enhanced by even just
> the addition of a bit of the usual client header line handling (would
> you look at that, Gemini supports three levels of it, and now we only
> *have* three levels of it in the spec :).

Yes, I'd like to do this!  I've been meaning to write some quick little
scripts to convert text/gemini to text/plain (mostly just a matter of
wrapping to 80 columns) and to text/html, so I can move to maintaining
the spec, FAQ, etc. in text/gemini and automate the mirroring to Gopher
and HTTPS.  It will happen one day! :)

Cheers,
Solderpunk

PS: Or has somebody already written these tools?