Re: Documentation should rely on stylesheets for XML not txt tools
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 ___ freebsd-doc@freebsd.org mailing list https://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"
Re: Documentation should rely on stylesheets for XML not txt tools
On Fri, Jul 06, 2018 at 10:06:39PM +0200, Sid wrote: > Whenever an improvement is suggested for documentation at FreeBSD's > bugzilla, it sits there for months or even over a year. Unfortunately this is not limited to doc PRs. We do a little bit better at ports due to the "maintainer" concept. We definitely need more people working on both documentation and getting PRs fixed. > Parts of the Handbook are outdated I'd like to see this situation get fixed. OTOH I am personally overcommitted. If you see anything that is especially stuck, feel free to add me to the Cc: line. It is also fair to note that many doc committers are using Phabricator (https://reviews.freebsd.org) for patch submissions. My view is that it's slightly better for patch reviews and Bugzilla is slightly better for actual bug submissions. mcl ___ freebsd-doc@freebsd.org mailing list https://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"
Re: Documentation should rely on stylesheets for XML not txt tools
On Sat, Jul 07, 2018 at 09:16:37PM +0200, Sid wrote: > 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 ___ freebsd-doc@freebsd.org mailing list https://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"
Re: Documentation should rely on stylesheets for XML not txt tools
Thank you for your response. The tools I'm referring to are igor and xmllint. Mention of igor is here, https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/overview.html . (the other link had the mistake of including the sentence punctuation) Mention of xmllint is in chapter 7.2. Other tools used are text editors in Chapter 15: Vim, Emacs, Nano The problem is not the text editors, because any and more should be allowed. Each one of these three text editors must have configuration set up, which is good, except when the program misbehaves. The set up for tabs is great, but to include them in checking for errors make it difficult. Earlier what I should have said is, there needs to be a parser that uses the FreeBSD stylesheet to fix the spacing and tabbing outside of XML elements, once or after it is submitted. Instead of igor, all that should be checked is the XML/Docbook syntax, and maybe spelling errors and FreeBSD jargon. I've tried editing on my pc, but once I edit an indent or spacing, I can't get it back, without getting rid of spacing errors on igor. I know I lack understanding of something for that to happen, but it is complex beyond necessity, and I get errors popping up in chapters I didn't touch. 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. Simplifying it wouldn't hurt with retaining contributors. Also, I would like to see the ability for edits to be made based from inside elements of the id attribute of a chapter or part. For example (not a Docbook example) In other words, the line numbering would start from an id attribute within a part or chapter, and the submission would be based on the opening and closing elements from that id in that part or chapter. > Saturday, July 07, 2018 at 10:56 AM, > > Fri, 6 Jul 2018 at 17:41, > > > > I'm aware of FreeBSD's XSLT and DSSSL stylesheets, mentioned at > > https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/stylesheets.html > > but they should be used exclusively for its Docbook XML. > > > > XSLT's stylesheet needs to be a part of automating of tabbing and stripping > > of spacing outside of element tags for .txt and other formats. > > Can you give me an example of a text tool we use? I'm not sure of what you > mean. > > Eitan Adler ___ freebsd-doc@freebsd.org mailing list https://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"
Re: Documentation should rely on stylesheets for XML not txt tools
On Fri, 6 Jul 2018 at 17:41, Sid wrote: > > I'm aware of FreeBSD's XSLT and DSSSL stylesheets, mentioned at > https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/stylesheets.html, > but they should be used exclusively for its Docbook XML. > > XSLT's stylesheet needs to be a part of automating of tabbing and stripping > of spacing outside of element tags for .txt and other formats. Can you give me an example of a text tool we use? I'm not sure of what you mean. -- Eitan Adler ___ freebsd-doc@freebsd.org mailing list https://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"
Re: Documentation should rely on stylesheets for XML not txt tools
I'm aware of FreeBSD's XSLT and DSSSL stylesheets, mentioned at https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/stylesheets.html, but they should be used exclusively for its Docbook XML. XSLT's stylesheet needs to be a part of automating of tabbing and stripping of spacing outside of element tags for .txt and other formats. ___ freebsd-doc@freebsd.org mailing list https://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"
