From owner-freebsd-doc@freebsd.org Sat Sep 9 02:23:49 2017 Return-Path: Delivered-To: freebsd-doc@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 9A1D0E1C794 for ; Sat, 9 Sep 2017 02:23:49 +0000 (UTC) (envelope-from matthew.ahrens@delphix.com) Received: from mail-lf0-x22b.google.com (mail-lf0-x22b.google.com [IPv6:2a00:1450:4010:c07::22b]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (Client CN "smtp.gmail.com", Issuer "Google Internet Authority G2" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 2009D75681 for ; Sat, 9 Sep 2017 02:23:49 +0000 (UTC) (envelope-from matthew.ahrens@delphix.com) Received: by mail-lf0-x22b.google.com with SMTP id l196so8900565lfl.1 for ; Fri, 08 Sep 2017 19:23:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=delphix.com; s=google; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc; bh=4Zo3R73KSx+Zge1Ehyp36DXJhxip0y6nnpPryEsmSCs=; b=EQs3D1MoKHF+gsA6NOb9Y4b7Osts+v+QYrvOGjUujz5x74h2vQhetaT7wMfbJy9YWU zaJST5mS+/0XYTByi7A25+NU/5wMYV6/XJkSaPYyYLw/AVJVenDYTtWKeP7zbhPIkslq hbfzbxj45GPWHJCjM7JKCmJJmwA20HFj64yTE= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:in-reply-to:references:from:date :message-id:subject:to:cc; bh=4Zo3R73KSx+Zge1Ehyp36DXJhxip0y6nnpPryEsmSCs=; b=tkUJNCHZJZltYdN1AdL9SMEHMM/V+ntU0nl9lLT5j0W50lmizrNrEHRNfilwHKh5qB d7cGiiwgEjEZfGQqW3ZXAMPzkK6XmU+FFEav14Z2O+9+sBi4MaGUs8tRp/MvfULCAddq y0cGGDLBkswsZzk2eop8RjNOXo8yQUI2V87zitde3hzFio1PVcQKjZjqLrEpN9/ogHSg QIBrP7efly4E+ld/+fonCO+i0HIhQmEKwkjdC3zconV32CxvoSUVZqMYR/w6H3kxxwH6 gQuXZQNLeeo2aWwMINtR+KZjOX7TN+NRINbWVJxLpuTqwVYNu/p2boHkRBbVnRUBGv3o aRDQ== X-Gm-Message-State: AHPjjUjQLOAspLzKAGnTzPf+Keu4bHPMOmQaSWa8RBfDl0Z+F9NSzAso nVGUhu+fN8w4WSXt3tT01SWcVf1/FSfC X-Google-Smtp-Source: AOwi7QBmui4PRVniJ4p+eXPzu+Jbo9UFofW01atfz28SPDSjRlDzweoN4h6kbyU5qM+G5Vg+Yuyd2Z2eh9RX8Ez8Mhw= X-Received: by 10.25.22.106 with SMTP id m103mr1725229lfi.168.1504923827175; Fri, 08 Sep 2017 19:23:47 -0700 (PDT) MIME-Version: 1.0 Received: by 10.25.83.213 with HTTP; Fri, 8 Sep 2017 19:23:46 -0700 (PDT) In-Reply-To: <19090d61-57d1-e436-f1d1-4e6e49ec291e@FreeBSD.org> References: <19090d61-57d1-e436-f1d1-4e6e49ec291e@FreeBSD.org> From: Matthew Ahrens Date: Fri, 8 Sep 2017 19:23:46 -0700 Message-ID: Subject: Re: re-synchronize zfs man pages with illumos To: Andriy Gapon Cc: freebsd-doc@freebsd.org, freebsd-fs Content-Type: text/plain; charset="UTF-8" X-Content-Filtered-By: Mailman/MimeDel 2.1.23 X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 09 Sep 2017 02:23:49 -0000 Andriy, thanks for your continued efforts to improve OpenZFS on both FreeBSD and illumos. Anything we can do to ease porting changes both ways will be great. If you find things that could be improved in the illumos manpages, I'd be happy to help you get those upstream too. I'm not an expert in mandoc, but if you think the FreeBSD style or content is better than what was done in illumos, we should consider making changes in illumos too. --matt On Fri, Sep 8, 2017 at 3:07 PM, Andriy Gapon wrote: > > 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 > _______________________________________________ > freebsd-fs@freebsd.org mailing list > https://lists.freebsd.org/mailman/listinfo/freebsd-fs > To unsubscribe, send any mail to "freebsd-fs-unsubscribe@freebsd.org" >