Here is chapter 1 in an odt since it's a new work and I wanted to bang it out without formatting. I'll add it to the sources after I get a good start on Chapter 2 and post a patch. I assume phabricator the preferred tool for commenting on documents?
Russ On Mon, Oct 9, 2017 at 3:48 PM, Benjamin Kaduk <b...@freebsd.org> wrote: > On Mon, Oct 09, 2017 at 12:22:11AM -0700, Russell Haley wrote: >> On Mon, Oct 2, 2017 at 9:21 AM, Russell Haley <russ.ha...@gmail.com> wrote: >> > On Fri, Sep 29, 2017 at 7:58 AM, Warren Block <wbl...@wonkity.com> wrote: >> >> On Mon, 25 Sep 2017, Russell Haley wrote: >> >> >> >>> Thanks! I'll play with this on the weekend. >> >> >> >> >> >> Please create a review at https://reviews.freebsd.org/ and add me as a >> >> reviewer. >> >> >> >> Thanks! >> > >> > Will do. Just a progress update: I got the handbook sources and found >> > the section in chapter.xml. I created a Geany project with everyone's >> > raw notes and the sources. To be continued... > > IIRC Warren had volunteered to help get that text committed, but if > not, feel free to add me to the phabricator review when it's ready. > >> >> Hi, >> >> So I got a good chunk of work done moving koobs’ description into the >> correct format and then started looking at how everything hangs >> together. I don’t want to offend anyone on this list, but I think the >> organisation and some of the English in the first 4 chapters needs >> work. I know how hard it is to create content from nothing (and how >> easy it is to be critical), so my hat is off to the original content > > Given how deep a tangle of patchwork and incremental change on top of > incremental change it is, it's unsurprising that the overall organization > of things does not make the best of sense. > >> creators. However, what I would like to propose is this: >> >> 1) Re-write the introduction to describe what the ports system is and >> point to the correct references in the handbook for running ports. I >> would also include reference to how to use subversion (handbook) and >> the correct repository names. I would also point users to websvn. I >> would indicate that the pkg system works off of the ports and include >> some other helpful links such as freshports, github and the build >> system. I would include a paragraph about how bugillza can be searched >> for issues for ports and also describe how phabricator is used to >> submit new patches to the ports system. Finally, it should be >> emphasised that anyone can create a new port for their software and >> submit it to the system. >> >> 2) The second chapter should be a description of how the ports system >> works. This description can be found in the how things work section of >> chapter 4. Include further description of the make files and where >> they can be found. A note should be made that while the makefiles are >> source code, they are well documented at the top and can be referenced >> when needed for more information. Chapter 2 should describe how >> additional targets can be created (content also from chapter 4). >> >> 3) Chapter 3 should remain and should be renamed Port Files Overview >> (or something to that effect). The first page should outline the files >> and involved. Most of them are quite simple and dedicating an entire >> ‘section’ to each step is cumbersome. Section 3.1 and 3.2 should be >> combined and beefed up (not sure the name yet). Section 3.3. and 3.4 >> should be combined and called Validation and Verification (or >> something to that effect). A description of what portlint does should >> be added. The new "V&V" section should describe why testing is >> important and what things to pay attention to, as well as reference >> the do’s and don't s section. >> >> 4) Chapter 4 should be called adding or updating ports. It should >> briefly describe what should be done to create a new port and then >> describe the processes as outlined by koobs'. The manual porting >> instructions should be removed. >> >> If there is any interest in me doing this, please speak up now as I >> might be able to take a day off this week and bash it out in one >> sitting. Okay, it's late... > > This sounds like a pretty good strategy, especially the part where > we actually introduce the subject matter! > > I don't want to tell you to take a day off, but would be happy to > see something like this appear eventually. > > Thanks for putting these thoughts together, > > Ben _______________________________________________ freebsd-ports@freebsd.org mailing list https://lists.freebsd.org/mailman/listinfo/freebsd-ports To unsubscribe, send any mail to "freebsd-ports-unsubscr...@freebsd.org"
