From owner-freebsd-doc@freebsd.org Sun Jul 8 07:39:31 2018 Return-Path: Delivered-To: freebsd-doc@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 3EB7DFF8EC8 for ; Sun, 8 Jul 2018 07:39:31 +0000 (UTC) (envelope-from sid@bsdmail.com) Received: from mout.gmx.com (mout.gmx.com [74.208.4.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (Client CN "mail.gmx.com", Issuer "thawte SSL CA - G2" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id B33F586333 for ; Sun, 8 Jul 2018 07:39:30 +0000 (UTC) (envelope-from sid@bsdmail.com) Received: from [108.70.50.7] ([108.70.50.7]) by web-mail.mail.com (3c-app-mailcom-lxa03.server.lan [10.76.45.4]) (via HTTP); Sun, 8 Jul 2018 09:39:08 +0200 MIME-Version: 1.0 Message-ID: From: Sid To: "Mark Linimon" Cc: "Eitan Adler" , "freebsd-doc@freebsd.org" Subject: Re: Documentation should rely on stylesheets for XML not txt tools Content-Type: text/plain; charset=UTF-8 Date: Sun, 8 Jul 2018 09:39:08 +0200 Importance: normal Sensitivity: Normal In-Reply-To: <20180708005921.GC27243@lonesome.com> References: <20180708005921.GC27243@lonesome.com> X-UI-Message-Type: mail X-Priority: 3 X-Provags-ID: V03:K1:X1ugU1N89kjkr8XDnV0cf2EcGwZ5mu80UJwi1u2uAIUrnk06QAgvF3s54Pbxz0yb+b7n2 poH6NdtSLKwXFey1IuZqpJ2foxXJRaH8H/vORC46Dd8t+EtquJxeqeMDFIfqXsEJUnWHxR1rk+w9 pW3JFy+PSZaReJn07RFIViuwuYgIa9E/XfrPv7kB1xdi5Z/KpIcHKrWhxDgKluTeJbi/QAxJ7Fa5 nRLg1zd/DXilFCLKZmWD6VRPQiOKqmpVvWv85vPQyYiKur8ha7xJlJxF+MnvsLS8f7F7/5jIGH87 qY= X-UI-Out-Filterresults: notjunk:1;V01:K0:ixOpNk/BYtc=:7HADVt1edYlL5Fk/7y7ph2 pR6O2ILfObkrkFnB2gm2rmw7TItim8y3FvDm9UVvnvvH4VZ0q55q5ePhxaOI2PH+L/ko2XMwK jRWxMpJPRLOp2Hb+LjCIkKgTsXHezUQXe1ndXS2pcNkbmvels27mspWUs3W4WJtortFSHbvB5 i58ERrpR6vtxIBNdl/4a8KNHjxvmEHcHgy3bUcRnLA7z1BW6dmtGrQHo5QRrmzgWI8HjSiPKc ulbrEfQo7rarZ02L0qSvmwc3p0lpol/6CalBusNV5Rezpd8u+MpmOWnyXUM9tBROC8cqcvNxp kCX+Us4OH46LaZYgEhxgnd4ufriKYBWYqSMBgbfG7w8RFHDx6iZ2ZKNf95uqTZT4DeRPYES4j IBle6fIfx75BqPShkVR/k1RAwBV7JjHVTICCZdkfo4AbMHHnd3GwOU3WNNiaF3yQodK+SQUyb gERLdEDd0UcZdELvo4DMtC/dbp66vDnbecnL5s5whyow6m+l7RRAnsRbIg3ZyHs3fOUZfhWPZ 92kD/SziNaNgBdfCDXWzFC4ct9dI/mtdDp/LMB+y6aW X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.27 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 08 Jul 2018 07:39:31 -0000 XML and Docbook aren't the problem. The problem is that Docbook should be parsed according to stylesheets to take care of spacing to be converted to .txt, xml and other relevant outputs. XML serves a purpose, and the current tools for editing documentation are avoiding what XML was set to do, display text according to a style sheet. The igor checker gives too many errors, from sections I haven't touched. Igor for checking is not a clean method: it is complex in ways that aren't helpful, and the visual errors do not match with the formatting. Also, edits and line numbering should start at the chapter and end at the closing tag of that chapter, which id elements can be used for. If there are multiple check outs of a chapter for editing, there are more irrelevant but consequential errors from a book part, that easily conflict. As a contributor, I want to make edits according to grammar and Docbook specifications, without other presentational edits (especially on the right hand margin). I can try to fix the alignment on the right for hours, without making any progress, but instead churning up more spacing based errors in igor. It would be refreshing to use a program where, when Docbook is used properly and there are no spelling errors, the tool will display that there are no errors. Also, the job of committers needs to be made easier by using XML based tools, so they can do way more with less effort, so they won't be as overwhelmed. In the past, I've sent in edits both with Docbook formatting, and without Docbook formatting. For unmaintained sections of the Handbook, nothing happened with them. Sending an edit in Docbook formatting will make it easier for the committer. The current tools add excessive overhead that committers and those who want to send in edits according to the most helpful way don't need. The current tools are less helpful than to let XML do what it was meant for. It will allow contributors to focus more on content, and less on presentation. > > I think simplifying the process so that only Docbook needs to be > > learned well for edit proposals will make it easier for those > > submitting bug reports, and especially for committers. > > While I agree with this, I'd rather let people know that they should > feel free to update content without stressing out over the markup. > Fixing the markup is a mechanical thing that doc committers can/should > take care of. > > I'm much more concerned about getting our content fixed up :-) > > mcl