From owner-freebsd-ports@freebsd.org Wed Jan 4 09:50:53 2017 Return-Path: Delivered-To: freebsd-ports@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 F3AEFC9BDE2 for ; Wed, 4 Jan 2017 09:50:53 +0000 (UTC) (envelope-from woodsb02@gmail.com) Received: from mail-wm0-x229.google.com (mail-wm0-x229.google.com [IPv6:2a00:1450:400c:c09::229]) (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 88FC01F71 for ; Wed, 4 Jan 2017 09:50:53 +0000 (UTC) (envelope-from woodsb02@gmail.com) Received: by mail-wm0-x229.google.com with SMTP id t79so451460639wmt.0 for ; Wed, 04 Jan 2017 01:50:53 -0800 (PST) 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=Rk1vdP5x7KABKKUMlt7p7OxVBdfLhfCbXFmjhUTkyQ4=; b=sP2tyiqs9a0iHqWiXy4k8VDKuznIHklHvi81bnpMGPxYxWUE/pUdbTZeUJ2kHhq24b fkF0TfRqAIIEqLZrtgimr1VCXCYaXtD2JzGYbzNIEBA7koOIMZBY3I+1gDNZWVrcGkv8 f4pWJxJhHkC/Iibab9LUvKv3RQ+L6XGMoKToD7yKt/nVqthpFy5faNPmNAM6vr/B6Hn2 3Gddy4/coNR7gYqHwyybToHeT0YbHGUCKXLYud1XWt8Lypg+OWxfL6YRr/5PZ++3rNUc uiBlrAAm8sLLSa1ZFt3cOipKqXo0D/9aeXNlAyTeV6GHV3ZVJ/3yjR6xG/qqrsckEy4q hQSg== 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=Rk1vdP5x7KABKKUMlt7p7OxVBdfLhfCbXFmjhUTkyQ4=; b=KQISi06U74L7WNKGYpnEjfwa7QoUijnvacQSxS3T82TA05it++aw4Zv2iJil8qJkPk o17Tm97DqmKNDFlumD6jI3ICDOKaGI7NUewiGiTrVE4jUsZtsKwp5ecKmIr0Sx9iGnau Ayva3xFbDJ0OYTP8a6+c8+rwA11KiY+ST7n+f3steojcaL47sNHwE+w8K/7rIpL+ELKs rebuDmucEDU7QqZMUMkH4bwZnnVz/gsSIS+zfNj0A8BZQhwEtfkXc3/MeRg4Fel+ZPhB 4a9Zir3hDLoV+Dcb8BIDxJTmxZQA92Clx/SLeWZkbG3wqus9Rvl9IdW8A2WAqpMkwmsM Ar+Q== X-Gm-Message-State: AIkVDXJVhH3IrUt2rXRoOwjLZGoQObhEX9J2zm/aBsHNkT7wGlGjXakh5+d5dsgiqcbKc0Vq656KpS1faJ/OHw== X-Received: by 10.28.145.210 with SMTP id t201mr45976043wmd.37.1483523451890; Wed, 04 Jan 2017 01:50:51 -0800 (PST) MIME-Version: 1.0 Received: by 10.194.240.4 with HTTP; Wed, 4 Jan 2017 01:50:51 -0800 (PST) In-Reply-To: <76519193d791325700c3beb34b8f447b@acheronmedia.com> References: <76519193d791325700c3beb34b8f447b@acheronmedia.com> From: Ben Woods Date: Wed, 4 Jan 2017 17:50:51 +0800 Message-ID: Subject: Re: Ports' tips and gotchas To: "Vlad K." Cc: FreeBSD ports Content-Type: text/plain; charset=UTF-8 X-Content-Filtered-By: Mailman/MimeDel 2.1.23 X-BeenThere: freebsd-ports@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Porting software to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 04 Jan 2017 09:50:54 -0000 On 4 January 2017 at 01:16, Vlad K. wrote: > On 2017-01-03 17:43, Adam Weinberger wrote: > >> >> pkg-message needs to contain only essential information, otherwise >> end-users will start to ignore them. I agree that tips should be >> shared, but putting it into SVN isn't the way to go. >> > > ... > Unfortunately, random blogs and websites are not good enough because the > information is "out there" and not immediately presented. However, now that > you mention it, adding wiki entries and then having a pkg-message contain > something along the lines of "Please consult > https://wiki.freebsd.org/Foo/Bar for important information before you > init/start/configure/migrate/update, ..." is a valid alternative and I > like it. In fact, I'll be reworking my Postgres patch to do just that, and > create an entry for Roundcube. > > However, what would be the best way to approach this via the FreeBSD wiki? > I'm sure that random wiki pages in various users' namespaces is not quite > the right thing to do. There currently are some ports Wiki pages but > they're all over the place and not nicely organized. > > Perhaps it is time we start a special Ports namespace that would allow us > to collate and list in one place all the user submitted wisdom and > important instructions? > I wanted to chime in with a +1 for this idea. I have often thought that the FreeBSD wiki should contain a space for ports help wikis, that can initially be created by the maintainer, but other's could also add their tips and tricks. It is often said that FreeBSD has great documentation, but only if the help you are looking for is in the handbook. For many ports this is not the case, and projects like ArchLinux have far better documentation for how to use their packages. Some examples where the FreeBSD handbook and wiki have entries which don't focus on explaining how the user should use the system / tips and tricks associated with how to use it with FreeBSD: Xfce - a few tips in the handbook, and porting status in wiki. Compare that to the extensive help provided in the ArchLinux wiki. https://www.freebsd.org/doc/handbook/x11-wm.html#x11-wm-xfce https://wiki.freebsd.org/Xfce https://wiki.archlinux.org/index.php/Xfce Samba - a bit more detail in the handbook this time, but no where near as much guidance as in the ArchLinux wiki: https://www.freebsd.org/doc/handbook/network-samba.html https://wiki.archlinux.org/index.php/Samba Some examples from Arch Linux that I think would make great FreeBSD wiki port help articles: https://wiki.archlinux.org/index.php/Thunar https://wiki.archlinux.org/index.php/ConsoleKit https://wiki.archlinux.org/index.php/Polkit https://wiki.archlinux.org/index.php/LightDM So what I would like: agree on a place/structure for maintainers to add "how to use this port / how it works / tips and tricks" information, and let's get to writing some! The wiki is a great place, due to the low barrier to entry, and low need to scrutiny due to it being somewhat "unofficial" or unsanitised. Regards, Ben -- From: Benjamin Woods woodsb02@gmail.com