docs: missing colon and line breaks (smoe:docs_testwriting_linebreaks)

[smoe]

Hello, the lines indented are causing trouble to the auto-translators somewhere between the .adoc and weblate. I have adjusted those to my liking and then (modestly) also introduced semantic line breaks elsewhere.
@petterreinholdtsen as the author and weblate thinkahead, I hope you can tolerate that, maybe even like it?

[petterreinholdtsen]

It is unclear to me exactly which problem you are trying to solve here, but if it is the existence of \n in the msgid strings, I suspect a patch like this might be a more useful set of changes:

--- ../docs/src/code/writing-tests.adoc 2023-07-11 16:59:20.841877435 +0200
+++ writing-tests.adoc  2023-07-11 17:03:40.472993561 +0200
@@ -60,42 +60,42 @@
 
 test::
    A program that is executed and its exit code and output checked using
-   either checkresult or expected.
+either checkresult or expected.
 
 test.sh::
    A bash script that is executed and its exit code and output checked using
-   either checkresult or expected.
+either checkresult or expected.
 
 test.hal::
    A HAL script that is executed using `halrun -f test.hal` and its exit code
-   and output checked using either checkresult or expected.
+and output checked using either checkresult or expected.
 
 .Test evaluation
 
- expected::
+expected::
    A file whose content is compared to the output from running the test
-   scripts.  If the test output is identical to the content of the
-   expected file, the test succeeds.
+scripts.  If the test output is identical to the content of the
+expected file, the test succeeds.
 
 checkresult::
    An executable file to perform more complex validation than just comparing
-   the output of a test script. It gets the filename of the test program as
-   its command line argument. The exit code of this program controls the result
-   of the test. If both `expected` and `checkresult` exist, only `checkresult`
-   is consulted to validate the test output.
+the output of a test script. It gets the filename of the test program as
+its command line argument. The exit code of this program controls the result
+of the test. If both `expected` and `checkresult` exist, only `checkresult`
+is consulted to validate the test output.
 
- xfail::
+xfail::
    If this file exist, a test failure is expected and does not cause
-   runtests to return an exit code signaling an error.
+runtests to return an exit code signaling an error.
 
- skip::
+skip::
    If this file exist, the test is skipped and not executed at all.
 
- control::
+control::
    This file can be used to flag specific needs in the test.  At the
-   moment, the use of _sudo_ can be flagged, and tests requiring sudo
-   can be skipped when using `runtests -u`. To flag such requirements,
-   add a line with `Restrictions: sudo` to this file.
+moment, the use of _sudo_ can be flagged, and tests requiring sudo
+can be skipped when using `runtests -u`. To flag such requirements,
+add a line with `Restrictions: sudo` to this file.
 
 == Some testing approaches
 

This ensure only the first line is indented after ::, and cause po4a to correctly parse blocks of text into complete msgid entires without any newline.

I verified this by adding writing-tests.adoc to the po4a-demo branch I created earlier for your benifit, and looked at the generated pot file to ensure no string had unwanted newline in it.

[smoe]

Yes! Lovely! I'll update my patch accordingly - one second.

[smoe]

Ok. Now, we have some final disagreement on how semantic the line breaks shall be, also when this does not affect weblate. If you do not like what I came up with then please just apply the patch you came up with and close this PR - this is basically a style guide discussion now - and I do not know if this needs to be in the style guide in the first place or should just be left to the discretion of the individual contributing authors.

[smoe]

The build error is not related to this patch.

[petterreinholdtsen]

[Steffen Möller]

Ok. Now, we have some final disagreement on how semantic the line breaks shall be, also when this does not affect weblate.

I prefer shorter lines myself, with less than 80 characters per line. I find them easier to read. I assumed earlier that 'semantic line break' refered to structuring the text in a way that ensured translators got a semantic group of words presented to them, pressumably on Weblate. I am less sure what you talk about when the line break placement is not relevant for what is presented to translators. To be clear, I would like the strings included in a msgid to be a complete sentence, not sentence fragments, to make it possible to translate them. If a given line need to be unbroken to make that happen, I prefer it to be long instead of short. But when the msgid content is not affected, I belive lines should stay below 80 characters.

…

-- Happy hacking Petter Reinholdtsen

[smoe]

Hm.