Re: Feedback: TAB-555 Bad sub-sectioning

[Patrick Durusau <patrick@durusau.net>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Rusty,

I did a bad job explaining that one. My bad.

Let's walk through a real example in your spec and see what you think.

2.2 Feature Bits is followed by 2.2.1 Legacy interface...

So I assume we agree that is the subject of my comment. Yes?

OK, so reading 2.2, I get the impression that we want to distinguish
two things. 1) the current standard for signaling features and, 2) the
legacy interface. Yes?

I ask because 2.2 starts:

"Each virtio device offers all the features it understands."

So at first blush I would say:

2.2 Features

2.2.1 Feature Bits Interface

2.2.2 Legacy Interface: A Note on transitions from earlier drafts

But I am assuming there that my 2.2.2 (your present 2.2.1) performs
the same task as the present 2.2 Feature Bits?

That is they are performing the same tasks, features, but do so
differently?

Yes?

Does that help?

Just trying to make sure we are on the same page.

No doubt you need to separate the legacy interface (I assume you are
going to retain that language) from the present interface. I was
suggesting a different way of separating it.

Hope you are at the start of a great week!

Patrick

PS: Apologies, I should have written more clearly.


On 02/13/2014 09:46 PM, Rusty Russell wrote:
> Hi Partick,
> 
> I disagree with this one:
> 
> In order to have a subsection, it is necessary to have at least two
> subsections. Thus: 1. Title 1.1 sub-title 1.2 sub-title is correct,
> but, 1. Title 1.1 sub-title 2. Title is incorrect. Just listing the
> incorrect sub-sections: 2.2.1, 2.4.3.1, 2.4.4.1, 3.1.1, 4.1.1.1,
> 4.3.2.1.1, 4.3.2.2.1, 5.1.3.1, 5.1.4.1, 5.1.6.2.1, 5.1.6.3.1,
> 5.2.3.2.1, 5.2.4.1, 5.2.5.1, 5.3.4.1, 5.3.6.1, 5.5.4.1, 5.5.6.1.1,
> 5.6.4.1, 5.6.6.1.1, 5.6.6.2.1, 5.6.6.3.1, and 6.1
> 
> A sole subsection without any contents in the section itself is
> almost certainly a mistake, but the general form of:
> 
> SECTION
> 
> words words word... ... lots of words.
> 
> SUBSECTION
> 
> more more words
> 
> Seems reasonable.  In fact, it's hard for me to see how to fix
> "2.4.4.1 Indirect Descriptors" without creating a fake subsection
> called "2.4.4.1 Normal Descriptors".
> 
> And if we were to fix these, we would no longer have the bright
> line which separates Legacy Interface sections.  This was initially
> going to be an entirely separate document, but consensus was that
> this compromise of separate sections was clearer.
> 
> Cheers, Rusty.
> 

- -- 
Patrick Durusau
patrick@durusau.net
Technical Advisory Board, OASIS (TAB)
Co-Chair, OpenDocument Format TC (OASIS)
Editor, OpenDocument Format TC, Project Editor ISO/IEC 26300
Former Chair, V1 - US TAG to JTC 1/SC 34
Convener, JTC 1/SC 34/WG 3 (Topic Maps)
Co-Editor, ISO 13250-5 (Topic Maps)

Another Word For It (blog): http://tm.durusau.net
Homepage: http://www.durusau.net
Twitter: patrickDurusau
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQIcBAEBAgAGBQJTAWGiAAoJEAudyeI2QFGoomgQAPW5XMYQbyUrGh/2sOztMX4X
v5n1NStrX7YthdxtzVO5HY44SqlHESwjWdK3Ffwn19LIUtE9UpooUAaNziWv3xgQ
5MvTaTpRbCSE6xwSuLSCH6BNHE/yle7F4impohQmRmrrYFLjOkv8B8ZzqARvsveN
40mqIkZPZrybag598BzzeG0jCwPEMqO70c3YxVCWFGBut1MuneSoYOB+HUdYRgdU
wNAXfvDZuC1050D8jTtsZ7+TcQQGqYURE8FfVhsftl5AZdXoD+NnymqPHZ/Y8mTL
jeVwjCMfZm7s6/1Dv5lqn4n8sBkguds9p3zXOBTz3Gstg1A4JQoZEuHSazlh1uIS
YuUQiK37Nc3qnGOgEjnWTOhWlW8uNJDheI+IwSEf09xYIIl5DqgG5nj92uX2LdCv
Wy15JMWT2C3w4o8YeOqm7I49zgO6M+FtvCvO/27wjmqnDD2vHfZgPvnV937hkwHq
D2naUmr7lPiIbrF2tXiS3eXezfD8uQXdaBAVAGQs0zo2G7vME6f6X2y2VNvQqsbX
guLDqmSvAJvVEF58Xk2inuh/QlTVngJuuf0A4Q5seOBjbMAEdFgOlY30HHDQZbqi
VlStnLLYEAEk8YCr6NNWURDnRRjCh/Upyl+jeueg0B3JrgFXZEf52wkvDUwL/HF7
s4wrn/gj1/XY38gwuREO
=hoGw
-----END PGP SIGNATURE-----