Contradictory Markdown conventions in conflict

[tokidev]

Hi, folks!

On your website, there at least two Markdown conventions in contentual
conflict.

At [1] in the section "Markdown Conventions", the second point says:

> * Hard wrap Markdown lines at 80 characters.

At [2] in the section "Markdown Conventions", the second point says:

> * Insert a newline at the end of each sentence.
>
> * Rationale: This practice is most appropriate for source that
> consists primarily of natural language text. It results in
> the most useful diffs and facilitates translation into other
> languages while mostly preserving source readability.

As long as there are no special reasons for these contradictory rules, I
suggest to resolve that conflict, e.g. by deleting one of those
convention lists and link to the other instead.

I prefer the latter convention point to keep (since most links point to
these [2] conventions and because of the given rationale -especially the
translation thing).


Why is this important? Well, there are lots of Markdown files with more
than one sentence per line or with partial sentences per line. Both
result in very ugly phrases to translate at Transifex. :S To be honest,
I lose my desire to translate such things. I guess that other
translators think alike.


Kind regards,
Tobias

[1] https://github.com/QubesOS/qubesos.github.io/blob/master/README.md
[2]
https://github.com/QubesOS/qubes-doc/blob/master/basics_user/doc-guidelines.md

[Jean-Philippe Ouellet]

The 2nd convention is the correct way forward. 1st one should be
removed (but still applies to source code).

I have a WIP script to convert all our existing Markdown to the 2nd
convention, but ensuring there are no edge cases is nontrivial. Is
your progress is blocking on a complete conversion? If so I'm happy to
move it up on my to-do list.

Regards,
Jean-Philippe

[Marek Marczykowski-Górecki]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

If we're going to re-upload source files to transifex, I think we should
improve the process first:

1. Wait/ask for enabling markdown support
2. Write a script (transifex cmdline tool config?) to do that.

2a. Make sure that already translated texts are converted and
re-imported (if needed).

And later: create appropriate workflow (a script) for retrieving
translated pages back. But this is another story - #2652.

> I have a WIP script to convert all our existing Markdown to the 2nd
> convention, but ensuring there are no edge cases is nontrivial. Is
> your progress is blocking on a complete conversion? If so I'm happy to
> move it up on my to-do list.
>
> Regards,
> Jean-Philippe
>

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQEcBAEBCAAGBQJZKDNDAAoJENuP0xzK19csTn0H/RKzS/varDfyO0qGWZWbsBo2
o6UaBpNEe4VyRPfMo/DECzzX0Q0RkJJ6CSOm1KXx4Bt8WE87kiGo/BqAa/q2N4H7
+Zxw4Q0cWmE4nSwg4J8qie8OMDHdcdHmsg7v/N5diC4juKsdypGrH0YxxEvqlulM
cHZAryz55f8qoddSo4ZyfIMeUMlryWV1qu/jS/xzz955Aoku/DSjdSGhNiCkz6ju
2mOMoSfYGQIURN4QPaMpYNQ6JNBzsaClPnazpK7YsbNEDz3lcKtE253f2teCOrDR
r5f3H8b6f9gY7Y1wudPyDdyxGKC9/u/stqkYHJOTqrMC2H5f/TocRVgOdqcT/Gc=
=gzfD
-----END PGP SIGNATURE-----

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Thanks, Tobias. The explanation for this contradiction is very simple
and boring: When we decided to change our convention to inserting a
newline at the end of each sentence [3], we updated the Markdown
Conventions on the Qubes website, but we forgot to update them on the
GitHub README. This is exactly why we don't like to have the same
content in more than on place: it inevitably becomes desynchronized. The
right solution is to deduplicate the content, so I've replaced the
duplicate content on the GitHub README with a link to the Documentation
Guidelines. Apologies for the confusion, and thank you for pointing it out.

> [1] https://github.com/QubesOS/qubesos.github.io/blob/master/README.md
> [2] https://github.com/QubesOS/qubes-doc/blob/master/basics_user/doc-guidelines.md

[3] https://github.com/QubesOS/qubes-issues/issues/2639

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org
-----BEGIN PGP SIGNATURE-----

iQIcBAEBCgAGBQJZKMgAAAoJENtN07w5UDAwlksP/0qTujBwnMmaG5UTEiLhgIpD
DUWTB66gV9kuKuahV02x1U/vxSC6L54Jwu303ZrJWEVb6f8Qls/SY4pfQe2IA6lB
YJs0kUxvpJSHlZGuAEYsSLolBwJa/hMgGQIuX29w8DFJ1vBK7LKGT0T2rPxDxXJB
gBVNZUtrkzqkPgkTZVIUeY8GlO0v2BaSKFNOT7CRlB2CsmA5EIJ26Sny9ad/cw4l
U0s6jv24EFR0rB+H/jmXRY45Plm3rVzjzgHrqxOnzneb7dPISB/XLbesNkEmkIBT
PFcDPRQEUG4EbyYCnn32KvoyNuq4OJuNI7YASwdY7y1rua0CSj12wY4LMcRVPYUP
YPNWZf0I1Amg+QgbSUwKbmefXXlEQcYBqPhEkmI0B9FKJjITnr+tC4Bvri462DQc
txNnlVQWaqpMEpd9LRgbN8eECTQON60RzdtTuLlQ8C3aMTbqMkMwI9hYfZzwNiVY
t1q360et8wuj/ExEa1G58yMHyO53HrIJ5PBKff4HrLYQ6MwA26hpNOmlzwnKvYYe
VpAkTGB1ppky8IyNszZqAmmX57l4Olsa9xqnGY5T3R9Yp/d9SkJ9vE8YUhWNeq2r
B51F4O5vGeOvvI8uG96RDHtrXa0oSPZS5hJSGGuyBPDpubcK3tMHTLHeSOqNiE0U
2bJ0Qks5WD3RPjmNWll4
=+i/1
-----END PGP SIGNATURE-----