From owner-freebsd-fs@freebsd.org Fri Sep 8 22:08:33 2017 Return-Path: Delivered-To: freebsd-fs@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 66D46E0DC00; Fri, 8 Sep 2017 22:08:33 +0000 (UTC) (envelope-from avg@FreeBSD.org) Received: from citapm.icyb.net.ua (citapm.icyb.net.ua [212.40.38.140]) by mx1.freebsd.org (Postfix) with ESMTP id 80E346D05C; Fri, 8 Sep 2017 22:08:32 +0000 (UTC) (envelope-from avg@FreeBSD.org) Received: from porto.starpoint.kiev.ua (porto-e.starpoint.kiev.ua [212.40.38.100]) by citapm.icyb.net.ua (8.8.8p3/ICyb-2.3exp) with ESMTP id BAA02683; Sat, 09 Sep 2017 01:08:29 +0300 (EEST) (envelope-from avg@FreeBSD.org) Received: from localhost ([127.0.0.1]) by porto.starpoint.kiev.ua with esmtp (Exim 4.34 (FreeBSD)) id 1dqRRt-000JVH-CU; Sat, 09 Sep 2017 01:08:29 +0300 To: freebsd-doc@FreeBSD.org, freebsd-fs@FreeBSD.org From: Andriy Gapon Subject: re-synchronize zfs man pages with illumos Message-ID: <19090d61-57d1-e436-f1d1-4e6e49ec291e@FreeBSD.org> Date: Sat, 9 Sep 2017 01:07:33 +0300 User-Agent: Mozilla/5.0 (X11; FreeBSD amd64; rv:52.0) Gecko/20100101 Thunderbird/52.3.0 MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit X-BeenThere: freebsd-fs@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Filesystems List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 08 Sep 2017 22:08:33 -0000 Originally ZFS manual pages were written using a different formatting language from what we use in FreeBSD. I am not very knowledgeable in this area, but the experts should recognize the language by things like \fB, \fR, etc. Martin Matuska (mm) converted the manuals to the FreeBSD mdoc in r228019 https://svnweb.freebsd.org/base?view=revision&revision=228019 Recently illumos switched to using mdoc format as well. That happened gradually and the changes were usually mixed with other changes. For example, the zpool manual was converted in this change: https://svnweb.freebsd.org/base?view=revision&revision=318936 https://github.com/illumos/illumos-gate/commit/c8323d4323a565676ba44883bfeb289d9ed8813e It is not surprising, of course, that the illumos mdoc pages are quite different from their FreeBSD counterparts given the independent conversions. So, at the moment we have several classes of differences that are not easy to identify via textual differences of the source files alone. 1. Differences in the content due to underlying differences between illumos and FreeBSD, e.g. zones vs jails or different sample disk names, etc. 2. Whitespace differences where exactly the same words are split differently between the lines, etc. 3. Style differences. For example, explicit parentheses vs Pq/Po/Pc; use of Tn in FreeBSD; much more frequent use of Ns macro in illumos; quotes vs a different font (e.g. Qq vs Sy); etc. 4. Mistakes in either FreeBSD or illumos version. For example, the FreeBSD versions often continue a line after a period. 5. Independent / diverging language corrections. My impression is that the illumos pages are cleaner than the FreeBSD ones at the moment. My inclination is to suggest that we "restart" our pages from the current illumos pages and "rebase" FreeBSD-specific changes on top of those. I realize that that would be a lot of work. But the benefits are quite obvious as it would be much easier to merge changes both ways. Comments, suggestions, offers of help are all very welcome! Thanks. -- Andriy Gapon