Date: Sun, 8 Jul 2018 09:39:08 +0200 From: Sid <sid@bsdmail.com> To: "Mark Linimon" <linimon@lonesome.com> Cc: "Eitan Adler" <lists@eitanadler.com>, "freebsd-doc@freebsd.org" <freebsd-doc@freebsd.org> Subject: Re: Documentation should rely on stylesheets for XML not txt tools Message-ID: <trinity-3eb50bc4-32e6-462c-b56f-9838862546a6-1531035548964@3c-app-mailcom-lxa03> In-Reply-To: <20180708005921.GC27243@lonesome.com> References: <trinity-042910b1-1787-47de-9f63-cf67ff1c1053-1530924063293@3c-app-mailcom-lxa02> <CAF6rxgk-LTndZrP0FnQ6f7oKoHw8VBHHJ73jq=O=Ch%2BQOFtfBA@mail.gmail.com> <trinity-d1f136d4-00f0-42b3-8c7b-8d05005e71bf-1530990997468@3c-app-mailcom-lxa02> <20180708005921.GC27243@lonesome.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?trinity-3eb50bc4-32e6-462c-b56f-9838862546a6-1531035548964>