Date: Wed, 10 Feb 2021 17:03:48 +0100 From: Daniel Ebdrup Jensen <debdrup@FreeBSD.org> To: freebsd-doc@freebsd.org Subject: Re: Regarding AsciiDoctor and long lines Message-ID: <20210210160348.xfy3un6bx5u7cqvj@nerd-thinkpad.local> In-Reply-To: <c7d36625-0688-9ebb-de03-0e9b5eb55a82@freebsd.org> 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> <c7d36625-0688-9ebb-de03-0e9b5eb55a82@freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
--nqb62cxsvkfp3bxo Content-Type: text/plain; charset=us-ascii; format=flowed Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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 <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 di= ffs >>>>> 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 t= he >>>>> documentation can be rather long. >>>>> >>>>> So I would love if it we can agree to wrap/justify lines to 72 column= s, >>>>> going forward whenever we touch files. >>>>> >>>>> I've already started doing this on the handbook/x11 chapter update th= at >>>>> 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 blan= ks >>>>> here?). >>>>> >>>>> For reference, my testing had led me to believe that AsciiDoctor does= n'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 em= pty >> 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 l= ist, >> ordered list, images, included files, and maybe with some custom extensi= ons. >> >> 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: >> >> =3D=3D 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. > >--=20 >Allan Jude >_______________________________________________ >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" 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 --nqb62cxsvkfp3bxo Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQGTBAABCgB9FiEEDonNJPbg/JLIMoS6Ps5hSHzN87oFAmAkA+RfFIAAAAAALgAo aXNzdWVyLWZwckBub3RhdGlvbnMub3BlbnBncC5maWZ0aGhvcnNlbWFuLm5ldDBF ODlDRDI0RjZFMEZDOTJDODMyODRCQTNFQ0U2MTQ4N0NDREYzQkEACgkQPs5hSHzN 87piLwf+Jy0B1Yi0hrWF8JwlXvbLAdvaNgCYXUEc4Jqj8/XrFosdm1ij4mjm95lL 6mN0pbcspcSzeZ8XgDv0yLIzTMb/eK48Kjx91zYjtX8JFTgQ60gOAHAvYRCWa2hs GKACDV4qqp9qTjRW/bxlcEkOMywOgjXrJsLEiJdeNF0nH2Eqtmf506l6Aovc2H11 KUuLlRW0dOHPla+mpfzh9OENFijWrzxkmDoN7RhKcsxhN9VQfoaNc0+aBtFbAgLD jhu+IQkmvYdOZUIAAK7H02zqZtoLGP2QNhUjEGOTUQQYzg3/9n5hKU8clQ2ruEsQ 4KnlwhcnnpgN21EKHkW8s2Gpo6Z2yA== =7g1f -----END PGP SIGNATURE----- --nqb62cxsvkfp3bxo--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20210210160348.xfy3un6bx5u7cqvj>