From owner-freebsd-doc@freebsd.org Fri Sep 8 22:34:41 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 725AFE0EF5C; Fri, 8 Sep 2017 22:34:41 +0000 (UTC) (envelope-from russ.haley@gmail.com) Received: from mail-lf0-x22e.google.com (mail-lf0-x22e.google.com [IPv6:2a00:1450:4010:c07::22e]) (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 ED5816DB77; Fri, 8 Sep 2017 22:34:40 +0000 (UTC) (envelope-from russ.haley@gmail.com) Received: by mail-lf0-x22e.google.com with SMTP id q132so8319089lfe.5; Fri, 08 Sep 2017 15:34:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc; bh=gFpsnnIFqYXLYl7f+rZd8tBy00VQ/mK1DtH6UIfbdjc=; b=WUVLf0ZwDz/g1NI1zmDXQ/1ta7KU6NrfMnnAKdFL5aS4AEKW62dtEEEhVYITUEtvgI lMb8qm0tQnWMwWx54xjJSEefXzLQB0aJc1ZDoBnBOFjha4RzghT5P2Qm1Rt5O3QZr78w Ugf/Y6AqZwju0Fwcc+ktYpo9wrhARy89pgWP9Xdks7DnuX8wXI6Pudu2joOErXHv6d2k TY9oUCYntpHB2ZdZCSgDxhvjbGMRNnyoJPwAFYBvefi+9aSpMySPEns2YMUi+HsKk8Xp W+CzIzHAeZ8GG0NuYfGeIvKzS7WYXUCAyc17DfagJdv4zKCtXiqPgu1+9h+nu8zVTLwe fCLA== 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=gFpsnnIFqYXLYl7f+rZd8tBy00VQ/mK1DtH6UIfbdjc=; b=kUZvF1ssYWsrT8Q+YxB1wdNjGIczduGZTkVwFNrGbfMarMw4dYyTJ7s9Lq0igPFV+Y 5DOZtZ71WUJk0cTTTWsGzpxu226ZCM7IJbTpwoAk3GJh5BhdzeAMDl2YDQS2DZEAj4iQ MAFLX5fdoHqU7DRuunocI9scn6lpJnanLN0PVYv2ubNdUDgpBDsl0jQsAsU9gZ+3cNPG yEyiDLtIcZyHFDWDWcbo6ZcYQN8lkfNQvTRelpDUMlP4lF0QDo1NXkvycFohZ90vrGlj DRhEap3aXW5IlsisqjDQw6/YZPFgLujvO7NhSIEMGbNXI1/94zVzWzlvOWlJa9zzJ25s l+qw== X-Gm-Message-State: AHPjjUjNOyZUnYMFGxfHz3ZYYKcMnozEDA+CjFLFe0rJfeU2DU+mkTZH bVIPSZUb5vkQEPuzQ95w4wbIhZfZd8wG X-Google-Smtp-Source: AOwi7QDcT2iy1jfKuFPTbg1xN/jDOkS66nFP8h1CNAiZt1bofaAt02x0rIewFx9OrJAT+NzkaGl3mCKVqt85R3HNmow= X-Received: by 10.46.83.23 with SMTP id h23mr1559099ljb.97.1504910078025; Fri, 08 Sep 2017 15:34:38 -0700 (PDT) MIME-Version: 1.0 Received: by 10.46.81.18 with HTTP; Fri, 8 Sep 2017 15:34:37 -0700 (PDT) In-Reply-To: <19090d61-57d1-e436-f1d1-4e6e49ec291e@FreeBSD.org> References: <19090d61-57d1-e436-f1d1-4e6e49ec291e@FreeBSD.org> From: Russell Haley Date: Fri, 8 Sep 2017 15:34:37 -0700 Message-ID: Subject: Re: re-synchronize zfs man pages with illumos To: Andriy Gapon Cc: freebsd-doc@freebsd.org, freebsd-fs@freebsd.org Content-Type: text/plain; charset="UTF-8" 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: Fri, 08 Sep 2017 22:34:41 -0000 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. I think anything that can be done to both strengthen the Illumos projects and create tighter coupling between BSD projects is a good thing. Documentation work is also an excellent way to learn a technology. I would happily contribute to this project and it would be a good one to push towards new comers looking to learn/leverage ZFS. It would also create an uptick in activity and could be used as advocacy/advertising in tech publications. ZFS is a big pull from GNU/Linux to FreeBSD. I also think that DTrace documentation on FreeBSD could use some cleanup and renewal. It's such an awesome feature. Russ