fixed #138

[VladimirAlexiev]

I took up @TallTed's suggestion about rule formatting. But I included some more formatting fixes. Hope I haven't overdone it, and the PR can be accepted!

---

Preview | Diff

[william-vw]

Many of these don't look like fixes, but rather like personal preferences on the use of spaces and newlines. There's no best practices on their use in N3, as long as indents aren't misleading (e.g., as to what property belongs to which resource). Thus, I'd opt not to merge this PR, unless a case can be made that the fixes, well, actually fix something.

[TallTed]

unless a case can be made that the fixes, well, actually fix something

My suggested tweaks to indentation and other whitespace are primarily made on examples which are provided for humans to read, not for machines to digest. @VladimirAlexiev's appear to be in the same vein. Thus, they don't "fix" anything in the sense I think you're asking for, but they certainly increase comprehension, in my experience, so... if that's something you value in this documentation for humans, I would suggest this be merged.

[william-vw]

@TallTed ... I think we all agree the goal is having examples for human consumption - if it wasn't, all of these would be minified one-line examples with only the minimal whitespace required by the grammar.

The PR is represented as a set of formatting fixes, so my question pertains to relevant formatting principles. These would be useful for other purposes as well, such as the automatic formatting of N3 code. In general, formatting of N3/Turtle code for readability is tricky - Jena applies a number of heuristics for it (e.g., depending on the length of predicates, number of object values and their length, ...). Here, the proposed updates seem rather arbitrarily decided.

Whatever is decided on the formatting of these examples, the benefit of particular principles should be well motivated.

[TallTed]

@william-vw —

I agree, it would be better if the guidelines of "human friendlier" formatting could be clearly stated and therefore followed by any and all.

And, on further review of this PR from @VladimirAlexiev, I disagree with many if not most of his proposed changes (a frequent change I notice is @VladimirAlexiev removing spaces between enclosing braces and the data enclosed therein, e.g., he's changing { :a :b :c } to {:a :b :c}, which I would not do because this can make it seem that the enclosed content is attached to the enclosing braces; my general practice is to increase optional whitespace for human-targeted data, though it may be reduced or removed for machine-targeted data).

So I guess I'm asking @VladimirAlexiev and you and any others who are interested, to participate with me in an Issue discussing such things (which I don't believe exists yet), before any large-scale changes are put through PR.

[william-vw]

@TallTed @VladimirAlexiev please feel free to update the relevant issue https://github.com/w3c/N3/issues/138 - or start a new one - with a discussion on rule formatting options. For now, I will close this PR.

[VladimirAlexiev]

I've added proposed "Formatting Rules" to https://github.com/w3c/N3/issues/138#issuecomment-1492912629. @william-vw and @TallTed please comment.

@TallTed

I disagree with many if not most of his proposed changes

I've added your suggestion "Surround punctuation (brackets, parentheses, commas, semicolons, dots) with spaces" even though I prefer no spaces.

Please specify in detail which other changes you disagree with. Thansk!