Date: Wed, 03 Jun 2020 21:52:37 -0600 From: Brandon Helsley <brandon.helsley@hotmail.com> To: Polytropon <freebsd@edvax.de> Cc: freebsd-questions@freebsd.org Subject: Re: Minimal skills Message-ID: <CY4PR19MB0104DD86F8FE6446AD1BF327F9890@CY4PR19MB0104.namprd19.prod.outlook.com> In-Reply-To: <20200604020051.0c02472d.freebsd@edvax.de> References: <CY4PR19MB0104A2C03F4D66A1DA251A23F9880@CY4PR19MB0104.namprd19.prod.outlook.com> <20200604005859.ca438474.freebsd@edvax.de> <CY4PR19MB0104C290121BF756D57B2DDBF9880@CY4PR19MB0104.namprd19.prod.outlook.com> <20200604020051.0c02472d.freebsd@edvax.de>
next in thread | previous in thread | raw e-mail | index | archive | help
You said there is different areas of documentation=2E Does this separation = of areas just go by the handbook's sections? Could this mailing list please= elaborate on the subject of updating documentation? and what it takes to d= o this? For a specific area that I'm interested in, that would be the Netwo= rk servers, firewall and advanced networking chapters, since this is what I= want to learn=2E I'm assuming that's what you had meant about being intere= sted in a particular area or documentation=2E Thank you for all the advice so far=2E Now I can get on track with the rig= ht direction for my education=2E I will make sure I learn a little programm= ing, learn unix and study some kind of computer science that supports all t= he rest=2E And then of course continue to use FreeBSD with the updating han= dbook=2E=20 Brandon On June 3, 2020 6:00:51 PM MDT, Polytropon <freebsd@edvax=2Ede> wrote: >On Wed, 03 Jun 2020 17:26:08 -0600, Brandon Helsley wrote: >> By "without any skills" I mean that I'm new to computers and >> am not even familiar with the terminology thrown around in >> the FreeBSD community=2E > >That's absolutely no problem=2E The more you use FreeBSD, the >better you will know the terminology, which is mostly out of >three classes: general computer terminology, UNIX terminology, >FreeBSD-specific terminology=2E It is important to understand >the meaning of termini technici originating in those classes, >and _what_ exactly to be "eloquent" at depends on the area >of documentation you want to deal with=2E > > > >> I've never heard of this documentation updating, I'd love to >> learn more=2E Who should I be talking to or where should I be >> referring to so I can learn=2E=2E=2E=20 > >The FreeBSD Documentation Project has its own sub-page: > > https://www=2Efreebsd=2Eorg/docproj/ > >Which can be reached from the central documentation site: > > https://www=2Efreebsd=2Eorg/docs=2Ehtml > >There is even a dedicated mailing list - freebsd-doc@freebsd=2Eorg >which is used to discuss documentation-specific issues=2E For use >with this mailing lists, as well as all other mailing lists, I >recommend this summary: > > https://www=2Efreebsd=2Eorg/doc/en_US=2EISO8859-1/articles/mailing-list-= faq/ > >Note that "documentation" doesn't just refer to manual pages; >it also includes project web pages, books and FAQ, publications, >maybe even the Wiki and other material=2E > >Note that the handbook you can access with your web browser >is, technically, nothing else than the same handbook you can >patch and rebuild on your local machine, be it HTML or PDF as >the target: Those results are generated from the same source=2E > >So for example, if you wanted to contribute to the handbook, >you'd obtain the latest version of it, and the required tools, >make your changes, test them locally, then create patches and >commit them (or send them in to be commited by someone else)=2E > >Instead, if you wanted to update OS manual pages, you'd obtain >the system's sources, modify and test the man page source file, >create a patch, and send it in=2E > >Your primary tool here is a text editor=2E Depending on your >individual preference, that could be vi, vim, emacs, mcedit, >joe, something X-based, whatever fits your needs=2E It does not >even matter=2E Reading "man diff" and "man patch" is probably >also a significant advantage=2E There are other tools that might >get involved=2E > >Allow me to drop a few relevant articles: > > 1=2E FreeBSD Documentation Project: Submitting documentation > I have written some documentation=2E How do I submit it? > > https://www=2Efreebsd=2Eorg/docproj/submitting=2Ehtml > > 2=2E FreeBSD Documentation Project Primer for New Contributors > > https://www=2Efreebsd=2Eorg/doc/en_US=2EISO8859-1/books/fdp-primer/index= =2Ehtml > > 3=2E Committer's Guide > > https://www=2Efreebsd=2Eorg/doc/en_US=2EISO8859-1/articles/committers-gu= ide/index=2Ehtml > >A bit more general: > > Contributing to FreeBSD > > https://www=2Efreebsd=2Eorg/doc/en_US=2EISO8859-1/articles/contributing/= index=2Ehtml > >As I mentioned, there is also a mailing list where you can >ask questions specifically related to documentation (and >this list, freebsd-questions@, is absolutely appropritate >for general questions such as this one)=2E > > > >> I sent a PR from some account I created about a bug in the >> loading of the kernel modules for bhyve=2E I'm starting to think >> I didn't quite format it correctly or rather communicate the >> issue correctly=2E I heard that filing PR's is also a good >> starting point to get involved=2E Could someone help me find >> the documentation that explains how to file a PR or update >> documentation=2E > >The most convenient way to send a bug report is to use the >following page: > > https://www=2Efreebsd=2Eorg/support/bugreports=2Ehtml > >You can even find a good outline of _how_ to file a bug report: > > https://www=2Efreebsd=2Eorg/doc/en_US=2EISO8859-1/articles/problem-repor= ts/ > >Older FreeBSD versions included a "send-pr" program=2E :-) > > > > >--=20 >Polytropon >Magdeburg, Germany >Happy FreeBSD user since 4=2E0 >Andra moi ennepe, Mousa, =2E=2E=2E --=20 Sent from my Android device with K-9 Mail=2E Please excuse my brevity=2E From owner-freebsd-questions@freebsd.org Thu Jun 4 05:41:40 2020 Return-Path: <owner-freebsd-questions@freebsd.org> Delivered-To: freebsd-questions@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 4F90532C440 for <freebsd-questions@mailman.nyi.freebsd.org>; Thu, 4 Jun 2020 05:41:40 +0000 (UTC) (envelope-from freebsd@edvax.de) Received: from mout.kundenserver.de (mout.kundenserver.de [212.227.17.13]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-256) server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "mout.kundenserver.de", Issuer "TeleSec ServerPass Class 2 CA" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 49cvm31YBhz3Xmg for <freebsd-questions@freebsd.org>; Thu, 4 Jun 2020 05:41:38 +0000 (UTC) (envelope-from freebsd@edvax.de) Received: from r56.edvax.de ([178.5.236.150]) by mrelayeu.kundenserver.de (mreue106 [212.227.15.183]) with ESMTPA (Nemesis) id 1MeC5x-1j9JUH3QPf-00bH8x; Thu, 04 Jun 2020 07:41:35 +0200 Date: Thu, 4 Jun 2020 07:41:34 +0200 From: Polytropon <freebsd@edvax.de> To: Brandon Helsley <brandon.helsley@hotmail.com> Cc: freebsd-questions@freebsd.org Subject: Re: Minimal skills Message-Id: <20200604074134.89eb6518.freebsd@edvax.de> In-Reply-To: <CY4PR19MB0104DD86F8FE6446AD1BF327F9890@CY4PR19MB0104.namprd19.prod.outlook.com> References: <CY4PR19MB0104A2C03F4D66A1DA251A23F9880@CY4PR19MB0104.namprd19.prod.outlook.com> <20200604005859.ca438474.freebsd@edvax.de> <CY4PR19MB0104C290121BF756D57B2DDBF9880@CY4PR19MB0104.namprd19.prod.outlook.com> <20200604020051.0c02472d.freebsd@edvax.de> <CY4PR19MB0104DD86F8FE6446AD1BF327F9890@CY4PR19MB0104.namprd19.prod.outlook.com> Reply-To: Polytropon <freebsd@edvax.de> Organization: EDVAX X-Mailer: Sylpheed 3.1.1 (GTK+ 2.24.5; i386-portbld-freebsd8.2) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-Provags-ID: V03:K1:oeHSG5ft0L9LuTN8aZs2v1smXuVL2Gor08ttMBkkU8LwHvTs/CZ EuTLFgv+9AeA8hdERde2xg/xmXH5WBuq6siZzkqLuVWMD4Ca6NJ/P3u55B03bHXybX3cByZ qMEwUfuHLuYW+b5KEw63eBfU1XPTvlRnxvjcofLHy8Z8aMecKds/W26WYKkSYjCFyka3KIG qZJyR7v5Az7hfIHff4JzQ== X-Spam-Flag: NO X-UI-Out-Filterresults: notjunk:1;V03:K0:pBjfzj5Wa6Y=:vQKuPbMdRdiVWJQJjl+YXt MPZWxM2JrPYlONe5gTpzHNiUCeSsfNrsrPfDHb//woMY8/5TzNwdK6Y6P5k+0MM7xoLGH2b6i EhD+j0QR4GQMTao1JYCEG3WmbjJaD4nBSN32Jut67nu4/P/x2zrB03fy2lZuU2jNtSZKE0r+p 9UhJi6H469YD8uBSUdD8s2zhyk2uAwDz3ByRwtdK0YXKLnliBDWFkn5CJ9aHo78F0hagh3SMr S4dFNzzuCGvsy35llV42NvaB8W3G23+cDfgmAM7eFTILFtLE0Sy7EmFvIxR5KU/gMxYWeZqFr 5oMsQdfWux2PdvFPAzpTwl4f4WXLdNTCpSu0xL1nHdFyGftNISLp4N8fb32Zhj0JsWka/JoAa Mw4c/2nFT0oRGeX9MaEo8Fzmieb9G4a+mA8wvRE2ak2fdPn4dcNZqGWCXdwzJnT0RNT4LtCGV 75Ayt9tSLkQLilxTBbqRmliMIQ0x40clHfilLXAU6vDujSDa3GK90+kC2x8Stp8zxFoXxW9Pq zhaFHfDLHdp2jFNi+7DD/n6rUHoQ0dcdZah6Gts1OHxKGdwbv+CDcGgSQ5q1uqxgHJaGCK9aB C2YzWiWpbwXIdAvNJMmLxS2tXXlOS/WRIZp7Ze0TVVZkwhEeuJB4wWgbXnzrjwzmfsdot2kAn zX26gQ0Ooc5fGf7awRkk1YgkwmgH83vQ76WXXjxmEUAPdVMzC+dsepLyC7KnD6QGcA1qTm8DX V8mjk4ATqywx4FTnD/1NNOr2+i/M08D59XzRe/joy7LtigN2pNHdB7CriTbmDAGkcydVBC8Vq bnJUL0qWKttOSON6h4ok6QADT2BMKi10JmDkVI3prao0Vyf/hF3zgqdGACYj1UKznZhG/2Qhr fniTqQl3hi+/dRcHOcng== X-Rspamd-Queue-Id: 49cvm31YBhz3Xmg X-Spamd-Bar: + Authentication-Results: mx1.freebsd.org; dkim=none; dmarc=none; spf=none (mx1.freebsd.org: domain of freebsd@edvax.de has no SPF policy when checking 212.227.17.13) smtp.mailfrom=freebsd@edvax.de X-Spamd-Result: default: False [1.67 / 15.00]; HAS_REPLYTO(0.00)[freebsd@edvax.de]; RCVD_VIA_SMTP_AUTH(0.00)[]; TO_DN_SOME(0.00)[]; MV_CASE(0.50)[]; HAS_ORG_HEADER(0.00)[]; NEURAL_HAM_SHORT(-0.07)[-0.072]; RCPT_COUNT_TWO(0.00)[2]; FREEMAIL_TO(0.00)[hotmail.com]; RECEIVED_SPAMHAUS_PBL(0.00)[178.5.236.150:received]; RCVD_TLS_LAST(0.00)[]; R_DKIM_NA(0.00)[]; FROM_EQ_ENVFROM(0.00)[]; MIME_TRACE(0.00)[0:+]; ASN(0.00)[asn:8560, ipnet:212.227.0.0/16, country:DE]; ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-0.10)[-0.099]; REPLYTO_EQ_FROM(0.00)[]; FROM_HAS_DN(0.00)[]; NEURAL_HAM_LONG(-0.56)[-0.556]; MIME_GOOD(-0.10)[text/plain]; DMARC_NA(0.00)[edvax.de]; AUTH_NA(1.00)[]; TO_MATCH_ENVRCPT_SOME(0.00)[]; MID_CONTAINS_FROM(1.00)[]; RCVD_IN_DNSWL_NONE(0.00)[212.227.17.13:from]; R_SPF_NA(0.00)[no SPF record]; RWL_MAILSPIKE_POSSIBLE(0.00)[212.227.17.13:from]; RCVD_COUNT_TWO(0.00)[2] X-BeenThere: freebsd-questions@freebsd.org X-Mailman-Version: 2.1.33 Precedence: list List-Id: User questions <freebsd-questions.freebsd.org> List-Unsubscribe: <https://lists.freebsd.org/mailman/options/freebsd-questions>, <mailto:freebsd-questions-request@freebsd.org?subject=unsubscribe> List-Archive: <http://lists.freebsd.org/pipermail/freebsd-questions/>; List-Post: <mailto:freebsd-questions@freebsd.org> List-Help: <mailto:freebsd-questions-request@freebsd.org?subject=help> List-Subscribe: <https://lists.freebsd.org/mailman/listinfo/freebsd-questions>, <mailto:freebsd-questions-request@freebsd.org?subject=subscribe> X-List-Received-Date: Thu, 04 Jun 2020 05:41:40 -0000 On Wed, 03 Jun 2020 21:52:37 -0600, Brandon Helsley wrote: > You said there is different areas of documentation. Does this > separation of areas just go by the handbook's sections? Please check the links I provided. Primarily FreeBSD documentation contains the handbook / FAQ / books / articles you also find on the web page, and then there is the manpages that accompany the OS install. Ports contain their own documentation, independent from FreeBSD, and usually maintained by the port's upstream. > Could this mailing list please elaborate on the subject of > updating documentation? and what it takes to do this? As I mentioned, one part of the _FreeBSD_ documentation is what you find in the documentation port (freebsd-doc), and the other part is in the OS (/usr/src). For FreeBSD documentation: To obtain a current ports tree, use the following commands (typical example): # portsnap fetch extract # cd /usr/ports/misc/freebsd-doc-en # make # make install You can then go ahead and work with the sources in the work directory, and use tools like diff to create your patches to submit. The FreeBSD ports collection is explained here: https://www.freebsd.org/doc/handbook/ports-using.html For manpages: You usually use the freebsd-update tool to install and update the "src" component (it should be the default already). But in this specific case, using the most current version of the sources probably is the better way, and this is done using the Subversion tool. Get the latest sources. Then you'll find manpages in /usr/src's subdirectories for all the components and sections. Again, you can use diff to create patches. The OS updating procedures are explained here: https://www.freebsd.org/doc/handbook/makeworld.html Of course you don't need to install the kernel and the OS userland - you just want the manpage source files. :-) Sidenote: You can obtain the most current ports tree with svn (Subversion) as well, but for a first impression, I'd say the convenient binary methods are a good point to start. However, in actual contribution, you'll always want the latest (!) version available, and that is what svn delivers. > For a specific area that I'm interested in, that would be the > Network servers, firewall and advanced networking chapters, > since this is what I want to learn. I'm assuming that's what > you had meant about being interested in a particular area or > documentation. That is a broad topic. :-) FreeBSD itself offers several aspects of networking servers, firewalls, and of course the whole networking stacks and drivers; and there are ports that contain stuff, first of all things like web servers. > Thank you for all the advice so far. Now I can get on track > with the right direction for my education. I will make sure > I learn a little programming, learn unix and study some kind > of computer science that supports all the rest. And then of > course continue to use FreeBSD with the updating handbook. If you don't mind, I'd suggest to dedicate a workstation PC or a laptop for FreeBSD, while having a second computer (or a smartphone) for web access (documtnation, mailing lists, or web forums). Start by installing FreeBSD. Set up your working environment. On the way of doing so, you will already learn a lot. Then examine what you _can_ contribute, and decide what you _want_ to contribute to. Depending on that decision, the steps to take (as mentioned above) are a bit different, still they share a certain skillset and tools. It also helps if you read (or at least skim through) the documentation that already exists, to get a feeling of what you will be dealing with. As I said, the FreeBSD documentation basically works with the port that turns input files into a variety of output formats, while the manpages use their own "language". You can easily check how those look like. You can also get an impression of the writing style and terminology used. Example manpage files can be found on any FreeBSD install in /usr/share/examples/mdoc/ where template files can be found. -- Polytropon Magdeburg, Germany Happy FreeBSD user since 4.0 Andra moi ennepe, Mousa, ...
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CY4PR19MB0104DD86F8FE6446AD1BF327F9890>