Date: Wed, 10 Feb 2021 09:52:26 -0500 From: Allan Jude <allanjude@freebsd.org> To: freebsd-doc@freebsd.org Subject: Re: Regarding AsciiDoctor and long lines Message-ID: <c7d36625-0688-9ebb-de03-0e9b5eb55a82@freebsd.org> In-Reply-To: <CAFwocyNttBcOvyYVcs9Mp12bEmiWFCV3vWZCxnixc2QjmQ9%2ByA@mail.gmail.com> References: <20210210135028.u2mm3bhwgep557vu@nerd-thinkpad.local> <CAL2%2B-iWpZQi-x4cMLqCMuMH22REirEChP6__m%2B5gd_ZRBwqvGg@mail.gmail.com> <20210210140716.pr6up7uxjdf2gydu@nerd-thinkpad.local> <CAFwocyNttBcOvyYVcs9Mp12bEmiWFCV3vWZCxnixc2QjmQ9%2ByA@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On 2021-02-10 09:31, Sergio Carlavilla wrote: > On Wed, 10 Feb 2021 at 15:07, Daniel Ebdrup Jensen <debdrup@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 >>> <debdrup@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-unsubscribe@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 Jensen > > Hi, > > 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-unsubscribe@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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?c7d36625-0688-9ebb-de03-0e9b5eb55a82>