working on faq/pf

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

working on faq/pf

Jeremy C. Reed
(Please carbon-copy me on replies.)

1) I have at least 35 changes covering missing commas, missing space,
fixing mispellings and various other minor improvements to the
faq/pf/*html files. (I have sent most of these to OpenBSD committer who
works on this.) It would be easier to have some (or all) of these
committed so I don't have to work on keeping multiple copies of the faq/pf
tree around for submitting future diffs.

And some other stuff to do:

2) I noticed that some topics are duplicated (including mispellings). I'd
like to consolidate some of the redundant information, in particular the
defining of the src_addr and dst_addr and port ranges in
faq/pf/filter.html and faq/pf/nat.html. Anyone working on that already?

3) Explain backslash means line continuation (is obvious, but # mark is
obvious too and that is documented multiple times).

4) Create four graphical figures for the few text-based diagrams. Not
important for text based browsers though.

5) Be consistent with "Note". Some are bold, some are all caps (NOTE), and
some have colon (Note:).

6) Be consistent with command line examples; some have a hash mark to
show it is a shell and some don't. (Using a # seems fine.)

7) Be consistent when referencing PF; the usage is now mixed: "pf",
"pf(4)" and "PF". I suggest using "PF" as appropriate and only pf(4) if
needing to talk about technical (or kernel) specifics.

8) On first reference of some RFCs, also give the RFC title.

9) Maybe get rid of "it's had" and use "it has had" for better
readability.

10) Include URLs to outside docs in actual text content to help those who
may have a PDF that doesn't follow links or for hard-copies. (Of course,
they could always read the printout and then go back to the pf docs and
then find the link and click on it.)

11) Maybe show how to flush rules or clear statistics. (-F is only
described in reference to a specific anchor.)

12) "self" is mention in "Specifying Addresses" but is never really
described.

13) Maybe include examples for various port ranges (and don't duplicate
this).

14) In "Checking NAT Status", also describe the MULTIPLE:SINGLE (since not
I don't think documented in man pages and if it is point to it). It
doesn't appear to be default TCP States (but is added in
pf_print_state.c). Where documented with pf source? (I saw it documented
somewhere, but can't find now.)

15) Also with same section, say that it is source:destination.

16) Rewrite the long sentence in faq/pf/rdr.html "Also be aware that since
translation occurs ..." (split into a couple sentences or reword).

17) The "Keyword Ordering" example in faq/pf/shortcuts.html shows use of
"label" but that is not documented elsewhere in the faq/pf.

18) Maybe explain or identify between different uses of the term
"options" (some are "set" options and others are options for different
features). I may have missed this in the faq/pf and maybe I am mistaken
about this, but someone may try to do "set ..." with some option that is
not available. (Clarification would be appreciated.)

19) In the "Configuring Queueing" section in faq/pf/queueing.html, quickly
(one sentence) mention what the original implementation of ALTQ is and
where it came from. Maybe the first sentence can be changed to:

 "Since OpenBSD 3.0, the Alternate Queueing (ALTQ) framework from the KAME
 Project has been a part of the base system. It provides flexible traffic
 scheduling and bandwidth rate limiting."

This also removed redundant "Alternate Queueing queueing
implementation".

20) Also in the "Configuring Queueing" section, where it describes each
syntax setting, maybe repeat the keywords too for some; for example:

Change:
<li><i>interface</i>
To:
<li><tt>on <i>interface</i></tt>

And change:
<li><i>bw</i>
to:
<li><tt>bandwidth <i>bw</i></tt>

and for a few others too.

21) In the faq/pf/perf.html, maybe point to benchmarks anyways, such as
Hartmeier's old "Design and Performance of the OpenBSD Stateful Packet
Filter" which provides a performance evaluation.

22) In the "FTP Client Behind the Firewall" section in faq/pf/ftp.html,
double-check the reference to "/usr/libexec/ftp-proxy". It appears that on
now in OpenBSD 3.8 this is in /usr/sbin instead.

Should this mention the differences between old proxy and new (aka pftpx)?

23) The "More Information on FTP" section only has one link. Maybe just
link to it above (previous section) for this one sentence and remove this
"More Information on FTP" section. Unless other information is to be
added?

24) Are there in basic features in PF that have been missed in the faq/pf?

25) Are there other keywords shown in examples, but never described in the
same document?

I can provide more patches for the above.

I see this www list has very little discussion (and more spam than
content).

I'd appreciate any feedback on this.

Please CC me on replies.

 Jeremy C. Reed

    BSD News, BSD tutorials, BSD links
          http://www.bsdnewsletter.com/

Reply | Threaded
Open this post in threaded view
|

Re: working on faq/pf

Jeremy C. Reed
> (Please carbon-copy me on replies.)

> And some other stuff to do:

> 12) "self" is mention in "Specifying Addresses" but is never really
> described.

Ignore that. For some reason when I first read the two sentences, the
sentences were unclear to me. It is defined.

> I can provide more patches for the above.

I started patching this some more. I now have at least 41 changes (from
12 html files).

Please CC me on replies.

 Jeremy C. Reed

    technical support & remote administration
          http://www.pugetsoundtechnology.com/

Reply | Threaded
Open this post in threaded view
|

Re: working on faq/pf

Michael Steinfeld
In reply to this post by Jeremy C. Reed
I prefer clean doc's..

but, I don't know how much people care about ..

 "missing commas, missing space,
fixing mispellings and various other minor improvements"

I'd like to see the entire openbsd faq cleaned up and  'styled' out in
a simple elegant way.. in fact, my mirror of the faq on my local
network will pass xhtml validation and has a simple stylesheet. Which
I prefer to use if I need to print something, or just simply navigate
with a little more visual pleasantry.

but again, nobody seems to really care all that much about the design
of w.o.o ( www.openbsd.org ) I am not sure if punctuations or correct
use of grammar falls into that category as well.....

still, I appreciate the time you spent on it ...

--mike




On 1/6/06, Jeremy C. Reed <[hidden email]> wrote:

> (Please carbon-copy me on replies.)
>
> 1) I have at least 35 changes covering missing commas, missing space,
> fixing mispellings and various other minor improvements to the
> faq/pf/*html files. (I have sent most of these to OpenBSD committer who
> works on this.) It would be easier to have some (or all) of these
> committed so I don't have to work on keeping multiple copies of the faq/pf
> tree around for submitting future diffs.
>
> And some other stuff to do:
>
> 2) I noticed that some topics are duplicated (including mispellings). I'd
> like to consolidate some of the redundant information, in particular the
> defining of the src_addr and dst_addr and port ranges in
> faq/pf/filter.html and faq/pf/nat.html. Anyone working on that already?
>
> 3) Explain backslash means line continuation (is obvious, but # mark is
> obvious too and that is documented multiple times).
>
> 4) Create four graphical figures for the few text-based diagrams. Not
> important for text based browsers though.
>
> 5) Be consistent with "Note". Some are bold, some are all caps (NOTE), and
> some have colon (Note:).
>
> 6) Be consistent with command line examples; some have a hash mark to
> show it is a shell and some don't. (Using a # seems fine.)
>
> 7) Be consistent when referencing PF; the usage is now mixed: "pf",
> "pf(4)" and "PF". I suggest using "PF" as appropriate and only pf(4) if
> needing to talk about technical (or kernel) specifics.
>
> 8) On first reference of some RFCs, also give the RFC title.
>
> 9) Maybe get rid of "it's had" and use "it has had" for better
> readability.
>
> 10) Include URLs to outside docs in actual text content to help those who
> may have a PDF that doesn't follow links or for hard-copies. (Of course,
> they could always read the printout and then go back to the pf docs and
> then find the link and click on it.)
>
> 11) Maybe show how to flush rules or clear statistics. (-F is only
> described in reference to a specific anchor.)
>
> 12) "self" is mention in "Specifying Addresses" but is never really
> described.
>
> 13) Maybe include examples for various port ranges (and don't duplicate
> this).
>
> 14) In "Checking NAT Status", also describe the MULTIPLE:SINGLE (since not
> I don't think documented in man pages and if it is point to it). It
> doesn't appear to be default TCP States (but is added in
> pf_print_state.c). Where documented with pf source? (I saw it documented
> somewhere, but can't find now.)
>
> 15) Also with same section, say that it is source:destination.
>
> 16) Rewrite the long sentence in faq/pf/rdr.html "Also be aware that since
> translation occurs ..." (split into a couple sentences or reword).
>
> 17) The "Keyword Ordering" example in faq/pf/shortcuts.html shows use of
> "label" but that is not documented elsewhere in the faq/pf.
>
> 18) Maybe explain or identify between different uses of the term
> "options" (some are "set" options and others are options for different
> features). I may have missed this in the faq/pf and maybe I am mistaken
> about this, but someone may try to do "set ..." with some option that is
> not available. (Clarification would be appreciated.)
>
> 19) In the "Configuring Queueing" section in faq/pf/queueing.html, quickly
> (one sentence) mention what the original implementation of ALTQ is and
> where it came from. Maybe the first sentence can be changed to:
>
>  "Since OpenBSD 3.0, the Alternate Queueing (ALTQ) framework from the KAME
>  Project has been a part of the base system. It provides flexible traffic
>  scheduling and bandwidth rate limiting."
>
> This also removed redundant "Alternate Queueing queueing
> implementation".
>
> 20) Also in the "Configuring Queueing" section, where it describes each
> syntax setting, maybe repeat the keywords too for some; for example:
>
> Change:
> <li><i>interface</i>
> To:
> <li><tt>on <i>interface</i></tt>
>
> And change:
> <li><i>bw</i>
> to:
> <li><tt>bandwidth <i>bw</i></tt>
>
> and for a few others too.
>
> 21) In the faq/pf/perf.html, maybe point to benchmarks anyways, such as
> Hartmeier's old "Design and Performance of the OpenBSD Stateful Packet
> Filter" which provides a performance evaluation.
>
> 22) In the "FTP Client Behind the Firewall" section in faq/pf/ftp.html,
> double-check the reference to "/usr/libexec/ftp-proxy". It appears that on
> now in OpenBSD 3.8 this is in /usr/sbin instead.
>
> Should this mention the differences between old proxy and new (aka pftpx)?
>
> 23) The "More Information on FTP" section only has one link. Maybe just
> link to it above (previous section) for this one sentence and remove this
> "More Information on FTP" section. Unless other information is to be
> added?
>
> 24) Are there in basic features in PF that have been missed in the faq/pf?
>
> 25) Are there other keywords shown in examples, but never described in the
> same document?
>
> I can provide more patches for the above.
>
> I see this www list has very little discussion (and more spam than
> content).
>
> I'd appreciate any feedback on this.
>
> Please CC me on replies.
>
>  Jeremy C. Reed
>
>                          BSD News, BSD tutorials, BSD links
>                          http://www.bsdnewsletter.com/
>
>


--
Michael Steinfeld

+=================================+
Is there such a thing as a rhetorical oracle?
+=================================+