Bug 76533
| Summary: | Misc punctuation fixes for the FW chapter. | ||||||
|---|---|---|---|---|---|---|---|
| Product: | Documentation | Reporter: | Brad Davis <so14k> | ||||
| Component: | Books & Articles | Assignee: | Giorgos Keramidas <keramida> | ||||
| Status: | Closed FIXED | ||||||
| Severity: | Affects Only Me | ||||||
| Priority: | Normal | ||||||
| Version: | Latest | ||||||
| Hardware: | Any | ||||||
| OS: | Any | ||||||
| Attachments: |
|
||||||
|
Description
Brad Davis
2005-01-21 12:40:26 UTC
Responsible Changed From-To: freebsd-doc->keramida I will work with Brad on this. Hi Brad, Impressive amount of cleanup. Thanks :-) Just a few comments, and an alternative patch that I may commit if you don't object to any of the changes I made... > - url="http://coombs.anu.edu.au/~avalon/ip-filter.html"></ulink> > - .</para> > + url="http://coombs.anu.edu.au/~avalon/ip-filter.html"></ulink>. > + </para> Closing tags should cuddle to the previous line. Whitespace at the end of the enclosed element is not really necessary and *may* be harmful if the SGML conversion process doesn't handle them correctly. > - 2 different modes that it can be used in. Native mode is the default > - mode when you type the command on the command line without the > + two different modes that it can be used in. Native mode is the > + default mode when you type the command on the command line without the Whitespace changes should *never* be mixed with content changes in the same patch chunk. Otherwise, the change s/2/two/ is fine here :-) > <para>To activate the changes to <filename>/etc/syslog.conf > </filename> you can reboot or bump the syslog task into > re-reading <filename>/etc/syslog.conf</filename> by running > - <command>/etc/rc.d/syslogd restart</command> (<command> > - kill -HUP <replaceable>PID</replaceable></command> in &os; 4.x. You get the PID (i.e. process > - identifier) by listing the tasks with the <command>ps -ax</command> > - command. Find syslog in the display and the PID is the number > - in the left column).</para> > + <command>/etc/rc.d/syslogd restart</command> > + (<command>kill -HUP <replaceable>PID</replaceable></command> > + in &os; 4.x. You get the PID (i.e. process identifier) by > + listing the tasks with the <command>ps -ax</command> command. > + Find syslog in the display and the PID is the number in the > + left column).</para> Missing closing parenthesis in the 4.X suggestion. This paragraph is also a bit strange. It goes into an excessive amount of trouble to explain what a PID is and suggest `ps -ax' for 4.X releases. The `killall' command is simpler IMHO. % <para>To activate the changes to <filename>/etc/syslog.conf % </filename> you can reboot or bump the syslog task into % re-reading <filename>/etc/syslog.conf</filename> by running % - <command>/etc/rc.d/syslogd restart</command> (<command> % - kill -HUP <replaceable>PID</replaceable></command> in &os; 4.x. You get the PID (i.e. process % - identifier) by listing the tasks with the <command>ps -ax</command> % - command. Find syslog in the display and the PID is the number % - in the left column).</para> % + <command>/etc/rc.d/syslogd restart</command> % + (<command>killall -HUP <replaceable>syslogd</replaceable></command> in &os; 4.X).</para> > <para>Warning, when working with the firewall rules, always, > always do it from the root console of the system running the > - firewall or you can end up locking your self out.</para> > + firewall or you can end up locking your self out. Or setup a > + cronjob to flush the Firewall rules say every 5 minutes. > + (This might not be acceptable for a corporate firewall, but > + should be for a home firewall.)</para> There is a capitalized "Firewall" word in the middle of a sentence. The two first sentences use 'or' too often and 'might' seems a bit funny near the beginning of the parenthesized sentence. The parentheses are also a bit redundant, IMHO. How about this, instead? % <para>Warning, when working with the firewall rules, always, % - always do it from the root console of the system running the % - firewall or you can end up locking your self out.</para> % + always do it on the console of the system running the % + firewall or you can end up locking your self out. % + Alternatively, you may setup a cronjob to flush the % + firewall rules say every 5 minutes. % + This may not be acceptable for a corporate firewall, % + but should be ok for a home firewall.</para> > @@ -820,7 +824,7 @@ > rule wins</quote> logic. For the complete legacy rule syntax > description see the &man.ipf.8; manual page.</para> > > - <para><literal>#</literal> is used to mark the start of a comment and may appear at > + <para>A <literal>#</literal> is used to mark the start of a comment and may appear at I'd probably write this as: <para>A <literal>#</literal> character... > - <para>Solution is to add filter rule like this one to get rid > + <para>The solution is to add filter rule like this one to get rid > of these unwanted log messages or do nothing and ignore FTP > - inbound error messages in your log. Not like you do FTP > - session to the public Internet all the time, so this is not > - a big deal.</para> > + inbound error messages in your log. Most people don't do > + outbound FTP too often.</para> "to add filter rule" sounds a bit funny and "don't" is a contraction that we will have to remove some time in the future anyway. I locally changed this paragraph to: % - <para>Solution is to add filter rule like this one to get rid % + <para>The solution is to add a filter rule to get rid % of these unwanted log messages or do nothing and ignore FTP % - inbound error messages in your log. Not like you do FTP % - session to the public Internet all the time, so this is not % - a big deal.</para> % + inbound error messages in your log. Most people do not use % + outbound FTP too often.</para> A complete copy of the modified patch (including some more fixes of numbers smaller than 10 that are spelled out as words) can be found at: http://people.freebsd.org/~keramida/files/brad-firewall.patch I'd be glad if you reviewed it, before I commit anything. - Giorgos From: so14k@so14k.com Subject: Re: docs/76533: Misc punctuation fixes for the FW chapter. Date: January 21, 2005 6:59:40 AM MST To: keramida@freebsd.org On Jan 21, 2005, at 6:34 AM, Giorgos Keramidas wrote: > Hi Brad, > > Impressive amount of cleanup. Thanks :-) > > Just a few comments, and an alternative patch that I may commit if you > don't object to any of the changes I made... > >> - url="http://coombs.anu.edu.au/~avalon/ip-filter.html"></ulink> >> - .</para> >> + url="http://coombs.anu.edu.au/~avalon/ip-filter.html"></ulink>. >> + </para> > > Closing tags should cuddle to the previous line. Whitespace at the > end of the enclosed element is not really necessary and *may* be > harmful if the SGML conversion process doesn't handle them correctly. I'm kind of confused about which part you are referring to here.. > >> - 2 different modes that it can be used in. Native mode is >> the default >> - mode when you type the command on the command line without >> the >> + two different modes that it can be used in. Native mode is >> the >> + default mode when you type the command on the command line >> without the > > Whitespace changes should *never* be mixed with content changes in the > same patch chunk. Otherwise, the change s/2/two/ is fine here :-) > >> <para>To activate the changes to <filename>/etc/syslog.conf >> </filename> you can reboot or bump the syslog task into >> re-reading <filename>/etc/syslog.conf</filename> by running >> - <command>/etc/rc.d/syslogd restart</command> (<command> >> - kill -HUP <replaceable>PID</replaceable></command> in &os; >> 4.x. You get the PID (i.e. process >> - identifier) by listing the tasks with the <command>ps >> -ax</command> >> - command. Find syslog in the display and the PID is the >> number >> - in the left column).</para> >> + <command>/etc/rc.d/syslogd restart</command> >> + (<command>kill -HUP <replaceable>PID</replaceable></command> >> + in &os; 4.x. You get the PID (i.e. process identifier) by >> + listing the tasks with the <command>ps -ax</command> >> command. >> + Find syslog in the display and the PID is the number in the >> + left column).</para> > > Missing closing parenthesis in the 4.X suggestion. This paragraph is > also a bit strange. It goes into an excessive amount of trouble to > explain what a PID is and suggest `ps -ax' for 4.X releases. The > `killall' command is simpler IMHO. > > % <para>To activate the changes to <filename>/etc/syslog.conf > % </filename> you can reboot or bump the syslog task into > % re-reading <filename>/etc/syslog.conf</filename> by running > % - <command>/etc/rc.d/syslogd restart</command> (<command> > % - kill -HUP <replaceable>PID</replaceable></command> in &os; > 4.x. You get the PID (i.e. process > % - identifier) by listing the tasks with the <command>ps > -ax</command> > % - command. Find syslog in the display and the PID is the > number > % - in the left column).</para> > % + <command>/etc/rc.d/syslogd restart</command> > % + (<command>killall -HUP > <replaceable>syslogd</replaceable></command> in &os; 4.X).</para> > >> <para>Warning, when working with the firewall rules, always, >> always do it from the root console of the system running >> the >> - firewall or you can end up locking your self out.</para> >> + firewall or you can end up locking your self out. Or >> setup a >> + cronjob to flush the Firewall rules say every 5 minutes. >> + (This might not be acceptable for a corporate firewall, >> but >> + should be for a home firewall.)</para> > > There is a capitalized "Firewall" word in the middle of a sentence. > The > two first sentences use 'or' too often and 'might' seems a bit funny > near the beginning of the parenthesized sentence. The parentheses are > also a bit redundant, IMHO. How about this, instead? > > % <para>Warning, when working with the firewall rules, > always, > % - always do it from the root console of the system running > the > % - firewall or you can end up locking your self out.</para> > % + always do it on the console of the system running the > % + firewall or you can end up locking your self out. > % + Alternatively, you may setup a cronjob to flush the > % + firewall rules say every 5 minutes. > % + This may not be acceptable for a corporate firewall, > % + but should be ok for a home firewall.</para> > >> @@ -820,7 +824,7 @@ >> rule wins</quote> logic. For the complete legacy rule syntax >> description see the &man.ipf.8; manual page.</para> >> >> - <para><literal>#</literal> is used to mark the start of a >> comment and may appear at >> + <para>A <literal>#</literal> is used to mark the start of a >> comment and may appear at > > I'd probably write this as: > > <para>A <literal>#</literal> character... > >> - <para>Solution is to add filter rule like this one to get rid >> + <para>The solution is to add filter rule like this one to >> get rid >> of these unwanted log messages or do nothing and ignore FTP >> - inbound error messages in your log. Not like you do FTP >> - session to the public Internet all the time, so this is not >> - a big deal.</para> >> + inbound error messages in your log. Most people don't do >> + outbound FTP too often.</para> > > "to add filter rule" sounds a bit funny and "don't" is a contraction > that we will have to remove some time in the future anyway. I locally > changed this paragraph to: > > % - <para>Solution is to add filter rule like this one to get > rid > % + <para>The solution is to add a filter rule to get rid > % of these unwanted log messages or do nothing and ignore > FTP > % - inbound error messages in your log. Not like you do FTP > % - session to the public Internet all the time, so this is > not > % - a big deal.</para> > % + inbound error messages in your log. Most people do not use > % + outbound FTP too often.</para> > > A complete copy of the modified patch (including some more fixes of > numbers smaller than 10 that are spelled out as words) can be found at: > > http://people.freebsd.org/~keramida/files/brad-firewall.patch > > I'd be glad if you reviewed it, before I commit anything. > I think it looks great. :) Thanks for your assistance. I feel kind of responsible for this chapter since I did a lot of the work to bring it into the tree in the sad state it is. How important is it to stick to the less than 72 characters per line rule? Regards, Brad Davis State Changed From-To: open->closed Committed. Thanks :) |
