From owner-freebsd-doc@freebsd.org Wed Feb 10 16:03:50 2021 Return-Path: Delivered-To: freebsd-doc@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 5AFF954ABA6 for ; Wed, 10 Feb 2021 16:03:50 +0000 (UTC) (envelope-from debdrup@freebsd.org) Received: from freefall.freebsd.org (freefall.freebsd.org [96.47.72.132]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "freefall.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4DbPh628YVz4fpB for ; Wed, 10 Feb 2021 16:03:50 +0000 (UTC) (envelope-from debdrup@freebsd.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1612973030; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=So1iXr7KIUUeVBrZ41dr+HddVy+YnqyfDMIaR19y8bc=; b=emjX0di02nKgC5THE4jGeiC34tqQ8sXiTRRcwPu3lYnsSZjDu1XUdKIWRvqZw/ZjbbdzD5 /tPcHKDEPli0QvoTcqKEBLU3O4FG7xs6wOa85lXjiUg1ZHnmEmANhF9kRov3HBF8t7EhGo 1EAov5FXYkiQLCJRvhVgTfCwg26ioSwYla2OHp2282NVdDANl6cWozl11wwzbWPHA6EdH6 EbrzGSoKl+fwMUO1hIoFb43rav6hk0GdCCLQhxMlJmr7WiLkrAkLy9nBGYc0QaplOmQNaa 44/M15lkuZVq5WNmenQv7a68ylnhkX5kgn4uRkQ3J/12pN1hRcC1d2Kwxd8D5g== Received: by freefall.freebsd.org (Postfix, from userid 1471) id 33ECEDD3C; Wed, 10 Feb 2021 16:03:50 +0000 (UTC) Date: Wed, 10 Feb 2021 17:03:48 +0100 From: Daniel Ebdrup Jensen To: freebsd-doc@freebsd.org Subject: Re: Regarding AsciiDoctor and long lines Message-ID: <20210210160348.xfy3un6bx5u7cqvj@nerd-thinkpad.local> References: <20210210135028.u2mm3bhwgep557vu@nerd-thinkpad.local> <20210210140716.pr6up7uxjdf2gydu@nerd-thinkpad.local> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="nqb62cxsvkfp3bxo" Content-Disposition: inline In-Reply-To: ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1612973030; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=So1iXr7KIUUeVBrZ41dr+HddVy+YnqyfDMIaR19y8bc=; b=mXMhCuFdmxkrCptvuDr7LRF8wuH3Ogpdv9Ac+V91adRQx4r2T+NYWpxg7eXaKXpiu2FCX7 83vgsAutN4KOSPGmst51oHvOAv8kxbnyVlNOMjZVi0C5iyV/PiGUxhHAqLFHiYLgotJIUx 6koer3V9wbPRimN0ZyEh4xxCw2XDR1PIp+nuquQzfU9B29lXzPlhxvFa07UYW91LYnFHZG 0wxrXDYZbLtN/1+YRpvXf3PdrxCUkKCwbtwulKESyeAQ/E1jA3Vtj/+CMcep6+a90dUPmK bP+ajW9qgPnaiNjBfYgl2FKn2wLpCI0Z3D4UVm19smPZZuDbU4SZ0odntdBc0w== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1612973030; a=rsa-sha256; cv=none; b=ZpRwMybtP3z2+Fv/mtm2nzrtjWzHYVhrbYRNno9vf/nsBOeW/6Eu9Jo6X7Fzq/RG7HZGJT pCYBqNmiamrUpF1gXtXvXmnf5uB/JTybXk5XW2D6cBeiYWXcTtrybwhwCaSdeMX+XoMMhk OIiMMrsVGA+R1vOyJ4psfg6FY5RA7QNhSCselaxyOh7MoOJppRSYLppMn3MGRoRrYjvhLz Vb77hn+sZl93C0nnnck3FSTt+wD5UR/oaH9xqTo7udtjzm7ZviTZ8Om8OfmfEITRDcGogO XAdbAXHSmcXCPcBCmc+PuxIDhG1vEOE589ZUIQcqjMaAoSTdregUBdx37NKvHw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 10 Feb 2021 16:03:50 -0000 --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 = 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 >>>> 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--