From owner-svn-src-head@FreeBSD.ORG Sun Apr 19 16:14:23 2015 Return-Path: Delivered-To: svn-src-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 5964D28B for ; Sun, 19 Apr 2015 16:14:23 +0000 (UTC) Received: from mail-wg0-x22a.google.com (mail-wg0-x22a.google.com [IPv6:2a00:1450:400c:c00::22a]) (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 E4FBAD12 for ; Sun, 19 Apr 2015 16:14:22 +0000 (UTC) Received: by wgsk9 with SMTP id k9so156092833wgs.3 for ; Sun, 19 Apr 2015 09:14:21 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=eitanadler.com; s=0xdeadbeef; h=mime-version:sender:in-reply-to:references:from:date:message-id :subject:to:cc:content-type; bh=5Rtl+OdZGJ12ciPXUcxy8int9EC1QGiqM5Mit1QJaRE=; b=PkWKUB3T22vNDhmLRXIs53lOYxHNe4xMCoIvtTZzAtNABmEKaFIhr6pErixN66N3OY 7OLfS4+5ZyZ8i+sqoV7Q/5yd0PsGSH+GjbXy2IEl5ICyVX/yEPZCgXYFVWX9WfOzPih4 Jc3BNDU5w3nef1tb5Pyniznxs+fZj3AOMW7fU= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:sender:in-reply-to:references:from :date:message-id:subject:to:cc:content-type; bh=5Rtl+OdZGJ12ciPXUcxy8int9EC1QGiqM5Mit1QJaRE=; b=bxEalIVxg+ktEU8cRu++Hl4Ue+hxid81VIAMPlWFhXvtrtzYcAdUS2jsxxR1YD3u7+ LEhS0/lTXeeY5NbgHODkqwN1h3NLIq0O/jJovnpAJKMebfLGnSuUMXvfzR4yduv+wDSQ 4XF8ggS+wSy8dhV6cuvqaB/agT5++9iVknnEe7/iMYeCniHUx/1FoTk9rloM+aBmArwe 2Qpr/Q7MOyqruWbGM/R4E8IG1Hd0W5VhLlBAN3pQQhy1ssskMnUmItraK/MKzpQx9vLd HfrODSXLclwtFAYbeCjR7hqUA0wPe//fh6Ulstkfhn1Wqx7qH8hBJWOuDfnMmv7LqdU4 igpg== X-Gm-Message-State: ALoCoQlKPUzjrAnpomnAinffeweGuJGWLwLoY/pBOiPTk1/EEjMq0q24AqrPn5JQHlhZ4C6RBDqF X-Received: by 10.180.81.104 with SMTP id z8mr17862608wix.5.1429460061310; Sun, 19 Apr 2015 09:14:21 -0700 (PDT) MIME-Version: 1.0 Sender: lists@eitanadler.com Received: by 10.28.211.135 with HTTP; Sun, 19 Apr 2015 09:13:50 -0700 (PDT) In-Reply-To: <1429458286.1182.89.camel@freebsd.org> References: <201504190716.t3J7GjmW072744@svn.freebsd.org> <20150419083451.GA79519@FreeBSD.org> <20150419153927.GA30772@FreeBSD.org> <1429458286.1182.89.camel@freebsd.org> From: Eitan Adler Date: Sun, 19 Apr 2015 09:13:50 -0700 X-Google-Sender-Auth: 5sLptwNR5HR53nfvgQSK-X5Y5ak Message-ID: Subject: Re: svn commit: r281727 - head To: Ian Lepore Cc: Alexey Dokuchaev , "src-committers@freebsd.org" , "svn-src-all@freebsd.org" , "svn-src-head@freebsd.org" Content-Type: text/plain; charset=UTF-8 X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 19 Apr 2015 16:14:23 -0000 On 19 April 2015 at 08:44, Ian Lepore wrote: > On Sun, 2015-04-19 at 15:39 +0000, Alexey Dokuchaev wrote: >> On Sun, Apr 19, 2015 at 01:42:08AM -0700, Eitan Adler wrote: >> > On 19 April 2015 at 01:34, Alexey Dokuchaev wrote: >> > > On Sun, Apr 19, 2015 at 07:16:45AM +0000, Eitan Adler wrote: >> > >> New Revision: 281727 >> > >> URL: https://svnweb.freebsd.org/changeset/base/281727 >> > >> >> > >> Log: >> > >> README: changes and fixups >> > >> Two orthogonal goals: >> > >> - try to make README look a little nicer on phabricator by using >> > >> Remarkup syntax for commands (using `` instead of using a >> > >> closing ') >> > >> - try to make README look a little nicer on github. >> > > >> > > FreeBSD had traditionally used both double (``...'') and single (`...') >> > > to express "literal" something; I am not convinced that changing it >> > > just to match GitHub's markdown warrants it. This `...` form is alien >> > > to FreeBSD, and can be also confused with backquoted form of shell's >> > > $(...) command substitution. >> > >> > Without this change, the syntax ends up being parsed very weirdly by >> > both phabricator and github. That said, if there is strong precedent >> > not to use the markdown syntax, and it would cause confusion, I will >> > revert those changes. >> >> I understand your reasons. I don't think we have any strong precedent >> for those things, but nor do I want to neglect the issue of markdowning >> our docs... Seeing /usr/ports/CONTRIBUTING.md already made me shiver. >> >> Since we control our own installation of Phabricator, maybe we should >> teach it to recognize ``...'' and `...' instead of converting them? >> (I don't know what to do about GitHub, but I don't like the idea that >> their markdown syntax inadvertently affects our files.) >> >> ./danfe >> > > Indeed, chasing the fad of the day seems like a Really Bad Idea. I know > people are religious about github and will bristle at labeling it a fad. > People had similar feelings about sourceforge a few years ago. We > wisely avoiding changing anything then, and we should do so some more. There is a difference between chasing the latest fad at the expense of the tools we already use, vs trying to allow users to do both. > Our readme and similar files are plain ascii text. If that confuses > github, then the fix needs to be applied at github. Note well: I avoided changing the files to be pure Markdown or Remarkup. I kept the files readable as plaintext. The goal of r281727 (this commit) was to - keep the plaintext readable - make it more readable on github - make it more readable on phabricator As an example, in the list of the 'source roadmap' only the entry usr.sbin has a single tab instead of double tab. This causes it to be non-tabular when parsed as GHB. I chose not to fix this, because it would break the plaintext alignment. Trying to get all three of these right is actually quite difficult :'( -- Eitan Adler Source, Ports, Doc committer Bugmeister, Ports Security teams