On Wed, Feb 10, 2021 at 09:52:26AM -0500, Allan Jude wrote:
On 2021-02-10 09:31, Sergio Carlavilla wrote:On Wed, 10 Feb 2021 at 15:07, Daniel Ebdrup Jensen <debd...@freebsd.org> wrote:On Wed, Feb 10, 2021 at 02:57:34PM +0100, Andreas B wrote:Have you considered one sentence per line? Ref. https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line. Andreas On Wed, Feb 10, 2021 at 2:50 PM Daniel Ebdrup Jensen <debd...@freebsd.org> wrote:Hi folks, Pursuant to a conversation that was had on #bsddocs on EFnet, this is mostly me wondering if we can adopt a new standard practice. Since the AsciiDoctor conversion, it's become evident that reading diffs which exceed the usual 72 columns that FreeBSD has standardized on for style(9) is less than great, especially as some of the sentences in the documentation can be rather long. So I would love if it we can agree to wrap/justify lines to 72 columns, going forward whenever we touch files. I've already started doing this on the handbook/x11 chapter update that I'm working on, and it's in line with what we're used to from DocBook, so I don't think it's too much of a big ask? :) We also need to decide about it relatively soon, since the Weblate project needs to know about about it, as it involves their use of .so files (although the details somewhat escaped me when I read it after staying up all night, so perhaps a domain expert can fill in the blanks here?). For reference, my testing had led me to believe that AsciiDoctor doesn't care one bit how it's styled, as long as the actual markup is kept the same. I'm open to feedback about it, of course, but it seems like a very sensible change to me. Yours hopefully, Daniel Ebdrup Jensen_______________________________________________ freebsd-doc@freebsd.org mailing list https://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"Sure, that seems like a nice compromise. I mostly want some kind of consensus so we can move forward without having to deal with these extremely long lines. ;) Yours, Daniel Ebdrup JensenHi, Personally I prefer to continue with the "one sentence per line". IMHO this allows people to get focused in writing text. But apart from what the AsciiDoctor recommends about using the "one sentece per line". There would be some problems with this approach. In the paragraph there's no problems because you can split a paragraph into multiple lines and it works well. For example, in AsciiDoctor this is the same: - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. D - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor In AsciiDoctor to create a new paragraph you have two options, keep a empty line between two lines or use the "plus" character. For example: This is a + line break. But you should use the "one sentence per line" in: headings, unordered list, ordered list, images, included files, and maybe with some custom extensions. For example, try to make this: * this is a very very very very (image reached the 72 characters) list * and this is the second item in the list Or for example: == This is a looooooooong (the same, we reached the 72 characters) heading I think you got the point. Maybe we can find a solution with the diff tool. Bye! _______________________________________________ freebsd-doc@freebsd.org mailing list https://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"There was also some mention that one sentence per line is helpful to the translators. The translation system will mark a re-wrapped line as 'fuzzy', and needing someone to re-confirm the translation. It isn't like they need to retranslate it, but, still. I imagine something like what we do for man pages, new sentence should always start on a new line. -- Allan Jude _______________________________________________ freebsd-doc@freebsd.org mailing list https://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"
Yeah, I'm perfectly fine with doing it like how manual pages work, ie. the one-sentence-per-line workflow, if I understand it. I'll be re-working the handbook/x11 chapter to that at some point. :) Yours, Daniel Ebdrup Jensen
signature.asc
Description: PGP signature
