Eine Reihe kleiner Inkonsistenzen

[Telofy]

Sorry für den wenig sprechenden Titel, aber ich bin jetzt endlich dazu gekommen, die ganze Spezifikation durchzulesen, und hab eine Reihe kleiner Inkonsistenzen gefunden, die ich unter keinem besseren Titel zusammenfassen konnte. Ich hab auch einen Pull-Request gestellt (#168), aber diese Punkte hier wollte oder konnte ich nicht eigenmächtig beheben.

1. In chapter_1050.md heißt es: »Gemeint sind selbstverständlich in allen Fällen immer weibliche wie auch männliche Personen.« Es gibt aber auch viele Menschen, die keinem dieser zwei Geschlechter angehören. Vielleicht: »Gemeint sind in allen Fällen Personen jeglichen Geschlechts.«

2. Zumal der Zeichensatz für die Callback-Funktion schon definiert ist, sollte man vielleicht auch die Länge begrenzen. (chapter_6040.md)

3. Sowohl modified als auch lastModified kommen vor, zum Teil in klarem Widerspruch. Ich vermute mal modified ist die korrekte Version.

   $ git grep lastModified
   chapter_6070.md:heißt hier die Eigenschaft für den Zeitpunkt der letzten Änderung `lastModified`. 
   chapter_6070.md:Auch hier gilt, dass der als `lastModified` ausgegebene Zeitpunkt auch als
   chapter_8040.md:`lastModified`
   chapter_8060.md:`lastModified`
   chapter_8090.md:`lastModified`
   

4. Im Pagination-Kapitel (chapter_6060.md) könnte man vielleicht nochmal an REST und Zustandslosigkeit erinnern, weil ein häufiger Weg, das umzusetzen, ist, für eine Session eine Suche abzuspeichern, die dann per ID in der URL angegeben wird (siehe z. B. ebook.de).

5. In chapter_6080.md unter »Weiterleitungen« werden die HTTP-Status-Codes 301 und 307 empfohlen (»SOLL«). Vielleicht sollte man von anderen Codes, die häufig für Weiterleitungen verwendet werden, explizit abraten (302 und 303).

6. In den Definitionen von Eigenschaften kommen einige Inkonsistenzen vor. Ich würde vorschlagen

   1. Erklärung, Typ und All-Caps-Hilfsverb jeweils mit einem Punkt dahinter zu schreiben, zumal der Zeilenumbruch von der Markdown-Datei verloren geht.
   2. das unveränderliche »Die Eigenschaft ist« überall wegzulassen.
   3. entweder »Zeichenkette« oder »String« zu schreiben, denn sonst könnten Leute denken der Standard mache dort einen idiosynkratischen Unterschied.
   4. entweder »Zeitstempel«, »Datum und Uhrzeit« oder »xsd:dateTime« zu schreiben, denn dito.
   5. sie einheitlich auf deutsch zu formulieren, da der Rest des Standards ja auch deutsch ist. (chapter_8140.md)
   6. Beschreibungen, die zwischen Singular und Plural schwanken zu vereinheitlichen (cf. Plural und Singular-Form von Begriffen #161, Eigenschaft "bodies" in oparl:System müsste eigentlich "body" sein #166), z. B. »Stichworte« vs. »Stichwort(e)«.

7. Die Bezeichnungen oparl:… sollten man entweder konsequent in freistehende Gravis fassen oder nicht, wobei auch Titel und dadurch mögliche Formatierungsprobleme zu beachten wären.

8. agendaItem heißt manchmal agendaitem.

   $ git grep "agendaitem"
   …
   chapter_8120.md:    "agendaitem": "https://oparl.beispielris.de/agendaitem/15569",
   chapter_8120.md:    "agendaitem": "beispielris:agendaitem/15569",
   chapter_8120.md:`agendaitem`
   

9. Eigentlich würde ich es nicht erwarten, aber da der Standard so viele andere Standards kurz erklärt, hat es mich verwundert, dass Popolo verwendet aber nicht erklärt wird.

10. Ist es wirklich wichtig den falschen Begriff »URL« statt »IRI« zu verwenden? So sind an mehreren Stellen Erklärungen dieses absichtlichen Fehlers nötig, die man sonst einsparen könnte, und »IRI« ist nicht einmal länger.

Unwichtiges

1. Die {#…}-Marken sind manchmal durch ein, manchmal zwei und manchmal drei Leerzeichen vom vorausgehenden Text abgegrenzt. Nicht, dass es einen semantischen Unterschied macht, aber ich hab’s immer hin- und hergeändert. Macht mich ganz kirre. ^^
2. Titel sind teilweise durch ### Ponies ### gemarkdownt, und teilweise nur durch ### Ponies.
3. Die JSON-LD-Standards, in die ich gerade reingeschaut hab (z. B. vom W3C), sprechen von compacted, expanded und flattened, nicht compact und flat. (chapter_6040.md)
4. HTTP-Header-Keys sind ja case-insensitive, aber vielleicht könnte man sie im Rahmen des Standards einheitlich schreiben. (Beispielsweise »Content-type« in chapter_6040.md vs. »Content-Disposition« in chapter_6080.md.)
5. Am Ende von Zeilen sind häufig Leerzeichen.
6. Man sollte entweder das englische »XML schema« (bzw. »XML Schema«) oder das deutsche »XML-Schema« einheitlich verwenden. Nicht, dass es häufig vorkommt. :-)

Welp, viel Flausch damit. Oder sagt Bescheid, wenn ich was helfen kann. Zum Teil geht es ja nur um Entscheidungen, die jemand fällen muss.

[akuckartz]

@Telofy Vielen Dank für die vielen Hinweise!

[akuckartz]

@Telofy Für diese Punkte wären PRs auf jeden Fall hilfreich (idealerweise ein PR pro Punkt):

• 1
• 3
• 4
• 6
  • I
  • II
  • III "Datentyp xsd:string" scheint am präzisesten zu sein. Der Zusatz "Datentyp" könnte sinnvoll sein, da kein IRI erwartet wird.
  • IV "Datentyp xsd:dateTime", "Datentyp xsd:date" etc.
  • V
  • VI "Stichwort" führt wohl zu größten Konsistenz
• 7
• 8
• "Unwichtiges"
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6

Diese Punkte schaue ich mir an:

• 5 siehe HTTP Status Code bei Zugriff auf erste Paging-Seite #147
• 9 siehe Kooperation mit Popolo Project #80

Für @marians zur Entscheidung:

• 2
• 10 IRI statt URL, (ich bin tententiell auch eher für IRI, weil das korrekter ist. Wir gehen (notwendigerweise) steilenweise derart detailiert auf technische Details ein, dass IRI kaum jemanden nennenswert verwirren dürfte.)

[akuckartz]

@Telofy Kommen hierzu noch weiter PRs ? ;-)

[Telofy]

Dies ist die Liste all derer Sachen, die ich mir nicht zugetraut hab, eigenmächtig zu entscheiden. Alles andere hab ich in dem Pull Request abgehandelt.

[the-infinity]

1, 2, 3, 6, 7, 8, 10: nicht mehr existent
4: #298
5: wäre eine Wiederholung