From owner-freebsd-doc@freebsd.org Fri Aug 31 19:02:16 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 A8C4DFD526B for ; Fri, 31 Aug 2018 19:02:16 +0000 (UTC) (envelope-from mpp302@gmail.com) Received: from mail-lj1-f172.google.com (mail-lj1-f172.google.com [209.85.208.172]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (Client CN "smtp.gmail.com", Issuer "Google Internet Authority G3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 308A280D40 for ; Fri, 31 Aug 2018 19:02:16 +0000 (UTC) (envelope-from mpp302@gmail.com) Received: by mail-lj1-f172.google.com with SMTP id v26-v6so10877509ljj.3 for ; Fri, 31 Aug 2018 12:02:16 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=RQ6aHLStoekAvVO8PWiXerxoemGFadUIe/jncViwKtc=; b=TPDhKDfbd5I5tAxywJt8MlbY0h4LY64yxF5HWYSZMR/5cCVahZ/XO8EB0nkMG9PxN6 5N9fmXDUbdjkLTLYW3cttyRq9CUX8AZWXyBAc8vWlDTtD+psEe9CUId17Wh0ZbpusYzg 8rChDP+PsZh1xIjAlURQdd0FKpyIYacuh3KOKjcPO9RNNUMUPwbDeOBehTzOCvQ+QxUj BbbYKHSC4SFe5G98cvitqZ/Q1tyje5+mr4FXIUNWNvSfUI//Q4Gm/Q3rpdOfp7mQ0t++ ZX4o3Pk5fdrrXMZkCOQf0uQjtxHqN+QxR+89yC8S4um+jtFI3ZiZdqbBKR6UkgGpW4Fp chKA== X-Gm-Message-State: APzg51BG+eM2xt+YQOlMHQDTOu8aOR8j7DIsD3G8eGr0JR+7fm6kYVjT YNRFSODXSVwhbFUnPvP0Mj6qaJUN X-Google-Smtp-Source: ANB0VdYwS38L5DDrsANYleVyWpNt/k8uwOGlk6O5kTY3OkBSKigGtcO86J32y+UaI9kUObBPS3i6bg== X-Received: by 2002:a2e:7113:: with SMTP id m19-v6mr11026491ljc.66.1535742128675; Fri, 31 Aug 2018 12:02:08 -0700 (PDT) Received: from e5500 (89-78-36-179.dynamic.chello.pl. [89.78.36.179]) by smtp.gmail.com with ESMTPSA id s74-v6sm2015656lfg.79.2018.08.31.12.02.08 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 31 Aug 2018 12:02:08 -0700 (PDT) Date: Fri, 31 Aug 2018 21:02:04 +0200 From: Mateusz Piotrowski <0mp@FreeBSD.org> To: Yuri Pankov Cc: freebsd-doc Subject: Re: option sort order in usage/man pages/documentation Message-ID: <20180831210204.734cc346@e5500> In-Reply-To: <9e434314-485d-6dd2-c7af-17ca0c49313c@yuripv.net> References: <9e434314-485d-6dd2-c7af-17ca0c49313c@yuripv.net> X-Mailer: Claws Mail 3.16.0 (GTK+ 2.24.32; i386-portbld-freebsd11.1) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit 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, 31 Aug 2018 19:02:16 -0000 Hello, On Thu, 30 Aug 2018 10:50:46 +0300 Yuri Pankov wrote: >I'm working on some man page updates, and, thinking about consistency, >been wondering if there's any policy set on the order of options that >one should use in usage messages/man pages/other documentation, i.e. is >it 'ABCabc', 'AaBbCc', or 'aAbBcC' (or anything else really, I hope >'unsorted' isn't possible answer here). FWIW, I've started creating a wiki page with some style guides for manpages. It'd be nice to move it to something like style.mdoc(5) later on: https://wiki.freebsd.org/MateuszPiotrowski/MdocStyleGuide At the moment my notes are focused mostly on the mdoc syntax. It would be great to add some guidelines for things like the sorting order. Apart from the order of 'ABCabc' we should also think about the order of long options ("--libxo") and command modifiers, which are sometimes included in the same list (although usually put at the end of it). Best, Mateusz