From owner-freebsd-doc@freebsd.org Fri Jul 6 20:06:51 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 2743A1026D72 for ; Fri, 6 Jul 2018 20:06:51 +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 A4F9094C24 for ; Fri, 6 Jul 2018 20:06:50 +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-lxa11.server.lan [10.76.45.12]) (via HTTP); Fri, 6 Jul 2018 22:06:39 +0200 MIME-Version: 1.0 Message-ID: From: Sid To: freebsd-doc@freebsd.org Subject: Documentation should rely on stylesheets for XML not txt tools Content-Type: text/plain; charset=UTF-8 Date: Fri, 6 Jul 2018 22:06:39 +0200 Importance: normal Sensitivity: Normal X-Priority: 3 X-Provags-ID: V03:K1:bgH+NcM13yMphErdZJqCD6m6cXyclBuTiSZqg/JR7dC36woYdP7ec17klPWsV5D6bRP62 6Z+WNECD5gFeUPXBE2J+LOKqruEvxdjEvGHNRKcABvBBvmcp7jMklkaQyYEuFxwQU9DhUd8ulZq4 xx/v7z5ug3kIF9RAiHD4ZlPga/4mX/TCFelxiMKP9NkpcIu1dxtNfFIwQDSWVNWZvC/6l82VmaOw qCASy/Wa8hxTxvMDz4Xodll61lHRsQKRoVoC9LEeS7w8rd7i8Kb/SpXPQuW5qfSgRJu6D4yZohSC yI= X-UI-Out-Filterresults: notjunk:1;V01:K0:/F9R4t5a+/Y=:+5YwVUFq2RiuXLFxACVgLg +EZOB1STA26g/LOTzbZtIMhZ9KHxV9rS20Nc12xej8H1S/2DccyhOfMhfEM5gKRu7Tw35SjsE WI2KNlmamyReIYl/6xat3H/CISQJBaPBggbTxwx8sHt+YCml3g3XbjQ2mDUWWj4ca0N3PPerB apnqAPRB6ffni76xCJoOe83MN/DpHT4xasVDIBJl4O6c0VvE4UkCtrjymUTc7kGaB2LVJ0sUt y/y+HFxMHlAkhVIhV4zZKHLINRJADb3it9U3VVIb6zhN1oJsWGiWUeuNuxhPLehnNOTJ+WiE/ BQe0BdlOJItWq3nSrUc102frkFBctgrxFm0DKCDR7V84RVBzUS+5jmIGs4qbfeXMVdHP0/Ojc Q8KEr0jQBaWZDGlcyXw0h8hbzDKxrrwR1/ILl/OlmEdfjOjQ3SVfCu3S9R9FWYre0iuAmXm1C yWwTTwBrqwD8zLW02rIDlRoLAa8UAPvzwwcbXzd1yoBusuzE6uNyoI8LzKmEhB20h5VqKLj4T JlWcojTR+cM2KxfzID6iP7BCP9H8JQAQ30ZSyLfiaZu 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: Fri, 06 Jul 2018 20:06:51 -0000 For spacing and presentation, FreeBSD documentation should rely on style sheets for XML, not on txt tools. XML is made for stylesheets to take care of its presentation. The requirement for improving documentation should be to learn XML and Docbook schema, and not other heavy (text based) tools that get in the way. Let a program take care of spacing that is outside of XML element tags. Text based tool igor doesn't cut it. Whenever an improvement is suggested for documentation at FreeBSD's bugzilla, it sits there for months or even over a year. Parts of the Handbook are outdated, and it seems like FreeBSD's bugzilla Documentation section is understaffed. For improvements to be made, the process must be simplified, and XML must be used how it is made to be used for simplification of that process. Igor and other text based tools add more overhead, more room for errors, more errors to correct (that are not based on Syntax, definitions, spelling errors, XML nor Docbook schema), many times more work, and it makes the work of contributors more difficult. Parts of the FreeBSD Handbook are outdated, and at this rate, this will not help expand FreeBSD's user base. Thank you