Porters Handbook section 4.4

[Russell Haley]

On Mon, Oct 2, 2017 at 9:21 AM, Russell Haley <russ.haley at gmail.com> wrote:
> On Fri, Sep 29, 2017 at 7:58 AM, Warren Block <wblock at 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...
>
> Russ


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
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...

Thanks,

Russ