Re: [leaf-devel] Documentation in Shorewall Configuration Files
On Sat, 2006-11-25 at 08:56, Tom Eastep wrote: Mike Noyes wrote: On Thu, 2006-11-23 at 08:48, Mike Noyes wrote: On Thu, 2006-11-23 at 07:26, Eric Spakman wrote: I don't know, a router/firewall is not really a good platform to read documentation... Maybe Erich's suggestion will work, creating some sort of webconf plugin package (lwp) so the docs can be read in a browser. I'm inquiring on the shorewall-devel list about possible xinclude of the new shorewall man pages in our leaf-doc-set. Eric, Apparently, the Shorewall man page xml source isn't available via uri. XInclude isn't an option for us. There is no reason why it can't be made available at the appropriate time. But the release of Shorewall 3.4 is still months away. Tom, Thanks for the clarification. :-) One caveat. Unlike the on-line documentation which makes it clear which releases of Shorewall contain individual features, the man pages will be targeted for only a single Shorewall release and will document the behavior of that release. Consequently, it important that the man pages be associated with exactly the right version of Shorewall. A single URI for publishing the XML source won't be able to meet that requirement. Understood. -- Mike Noyes mhnoyes at users.sourceforge.net http://sourceforge.net/users/mhnoyes/ SF.net Projects: leaf, phpwebsite, phpwebsite-comm, sitedocs - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT business topics through brief surveys - and earn cash http://www.techsay.com/default.php?page=join.phpp=sourceforgeCID=DEVDEV ___ leaf-devel mailing list leaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/leaf-devel
Re: [leaf-devel] Documentation in Shorewall Configuration Files
Eric Spakman wrote: Hi Paul, What troubles me more is that Tom updates the documentation on his site to represent the state of the art in shorewall v5, and the currently shipping versions of LEAF or BU are using shorewall v3, our documentation will not match the code we're shipping. snip There is no shorewall version 5, the current Stable Release version is 3.2.6 which is what we use. The development release is version 3.3.5, which will become 3.4.x when stable. When this version is stable, that one is going to be used in BU. Eric Sorry, that was a hypothetical. - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT business topics through brief surveys - and earn cash http://www.techsay.com/default.php?page=join.phpp=sourceforgeCID=DEVDEV ___ leaf-devel mailing list leaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/leaf-devel
Re: [leaf-devel] Documentation in Shorewall Configuration Files
Hi Paul, What troubles me more is that Tom updates the documentation on his site to represent the state of the art in shorewall v5, and the currently shipping versions of LEAF or BU are using shorewall v3, our documentation will not match the code we're shipping. snip There is no shorewall version 5, the current Stable Release version is 3.2.6 which is what we use. The development release is version 3.3.5, which will become 3.4.x when stable. When this version is stable, that one is going to be used in BU. Eric Sorry, that was a hypothetical. Ok, but back to the documentation issue. BU will always use the latest stable shorewall version and even with an older version of BU it shouldn't be a big problem to update to the latest shorewall (especially 3.0 onwards). Why duplicate the shorewall documentation on the LEAF site? Isn't it much simpler to just provide a link to Tom's documentation? Eric - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT business topics through brief surveys - and earn cash http://www.techsay.com/default.php?page=join.phpp=sourceforgeCID=DEVDEV ___ leaf-devel mailing list leaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/leaf-devel
Re: [leaf-devel] Documentation in Shorewall Configuration Files
On Thu, 2006-11-23 at 01:38, Eric Spakman wrote: Ok, but back to the documentation issue. BU will always use the latest stable shorewall version and even with an older version of BU it shouldn't be a big problem to update to the latest shorewall (especially 3.0 onwards). Why duplicate the shorewall documentation on the LEAF site? Isn't it much simpler to just provide a link to Tom's documentation? Eric, Aren't we discussing the Shorewall man page? The man page ships with Shorewall, but we strip it for size. This places an onus on us to provide the man page in some fashion. We are not duplicating anything Tom and the Shorewall team didn't intend for distribution. Am I missing something? -- Mike Noyes mhnoyes at users.sourceforge.net http://sourceforge.net/users/mhnoyes/ SF.net Projects: leaf, phpwebsite, phpwebsite-comm, sitedocs - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT business topics through brief surveys - and earn cash http://www.techsay.com/default.php?page=join.phpp=sourceforgeCID=DEVDEV ___ leaf-devel mailing list leaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/leaf-devel
Re: [leaf-devel] Documentation in Shorewall Configuration Files
Hello Mike, Ok, but back to the documentation issue. BU will always use the latest stable shorewall version and even with an older version of BU it shouldn't be a big problem to update to the latest shorewall (especially 3.0 onwards). Why duplicate the shorewall documentation on the LEAF site? Isn't it much simpler to just provide a link to Tom's documentation? Eric, Aren't we discussing the Shorewall man page? The man page ships with Shorewall, but we strip it for size. This places an onus on us to provide the man page in some fashion. We are not duplicating anything Tom and the Shorewall team didn't intend for distribution. Am I missing something? There are no shorewall manpages yet, this is something what will be introduced in shorewall 3.4 AFAIK. But when they are introduced, it shouldn't be a big problem to commit them to LEAF's manpage space. Or am I missing something? ;-) Eric - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT business topics through brief surveys - and earn cash http://www.techsay.com/default.php?page=join.phpp=sourceforgeCID=DEVDEV ___ leaf-devel mailing list leaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/leaf-devel
Re: [leaf-devel] Documentation in Shorewall Configuration Files
On Thu, 2006-11-23 at 06:50, Eric Spakman wrote: Hello Mike, Ok, but back to the documentation issue. BU will always use the latest stable shorewall version and even with an older version of BU it shouldn't be a big problem to update to the latest shorewall (especially 3.0 onwards). Why duplicate the shorewall documentation on the LEAF site? Isn't it much simpler to just provide a link to Tom's documentation? Eric, Aren't we discussing the Shorewall man page? The man page ships with Shorewall, but we strip it for size. This places an onus on us to provide the man page in some fashion. We are not duplicating anything Tom and the Shorewall team didn't intend for distribution. Am I missing something? There are no shorewall manpages yet, this is something what will be introduced in shorewall 3.4 AFAIK. But when they are introduced, it shouldn't be a big problem to commit them to LEAF's manpage space. Or am I missing something? ;-) Eric, Ah. We are in agreement then, or I think so. Do you still plan on a shordoc package? The post by Tom to you made me believe Shorewall man pages were available for current Bering-uClibc releases. -Forwarded Message- From: Tom Eastep [EMAIL PROTECTED] To: Eric Spakman [EMAIL PROTECTED] Cc: Leaf Development leaf-devel@lists.sourceforge.net Subject: Re: [leaf-devel] Documentation in Shorewall Configuration Files Date: Mon, 20 Nov 2006 11:25:24 -0800 Eric Spakman wrote: Hi Tom, I don't think that it's a big problem. We can always create a separate package shordoc, which contains the documentation, for people who need it or embed it in the shorwall package. We probably only need some help in creating a single text file from the manpages. rm -f Documentation for file in shorewall-release-dir/manpages/*.5; do man -l $file | col -bx Documentation done -Tom -- Mike Noyes mhnoyes at users.sourceforge.net http://sourceforge.net/users/mhnoyes/ SF.net Projects: leaf, phpwebsite, phpwebsite-comm, sitedocs - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT business topics through brief surveys - and earn cash http://www.techsay.com/default.php?page=join.phpp=sourceforgeCID=DEVDEV ___ leaf-devel mailing list leaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/leaf-devel
Re: [leaf-devel] Documentation in Shorewall Configuration Files
Hi Folks let me please chime in Mike Noyes wrote: On Thu, 2006-11-23 at 01:38, Eric Spakman wrote: Ok, but back to the documentation issue. BU will always use the latest stable shorewall version and even with an older version of BU it shouldn't be a big problem to update to the latest shorewall (especially 3.0 onwards). Why duplicate the shorewall documentation on the LEAF site? Isn't it much simpler to just provide a link to Tom's documentation? I suggest to build html pages from the shorewall documentation which could be inserted on demand using shorwall.lwp for those who run webconf. I personally liked the documentation within the config files, as they provided most of what I always needed. I have never looked into the size of the man command, it might also be nice to provide a man.lrp package for those with enough space. cheers Erich - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT business topics through brief surveys - and earn cash http://www.techsay.com/default.php?page=join.phpp=sourceforgeCID=DEVDEV ___ leaf-devel mailing list leaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/leaf-devel
Re: [leaf-devel] Documentation in Shorewall Configuration Files
On Thu, 2006-11-23 at 07:26, Eric Spakman wrote: Hi Mike, Eric, Ah. We are in agreement then, or I think so. Do you still plan on a shordoc package? I don't know, a router/firewall is not really a good platform to read documentation... Maybe Erich's suggestion will work, creating some sort of webconf plugin package (lwp) so the docs can be read in a browser. Eric, I'm inquiring on the shorewall-devel list about possible xinclude of the new shorewall man pages in our leaf-doc-set. The post by Tom to you made me believe Shorewall man pages were available for current Bering-uClibc releases. You copied the wrong part :-) Ah. Reading comprehension issue on my part. Sorry. :-( Quote: In Shorewall 3.4, the documentation will be removed from the files and will be replaced by manpages. This presents a problem for users of embedded distributions like Bering-uClibc who typically don't have access to manpages. -- Mike Noyes mhnoyes at users.sourceforge.net http://sourceforge.net/users/mhnoyes/ SF.net Projects: leaf, phpwebsite, phpwebsite-comm, sitedocs - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT business topics through brief surveys - and earn cash http://www.techsay.com/default.php?page=join.phpp=sourceforgeCID=DEVDEV ___ leaf-devel mailing list leaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/leaf-devel
Re: [leaf-devel] Documentation in Shorewall Configuration Files
On Thu, 2006-11-23 at 08:48, Mike Noyes wrote: On Thu, 2006-11-23 at 07:26, Eric Spakman wrote: I don't know, a router/firewall is not really a good platform to read documentation... Maybe Erich's suggestion will work, creating some sort of webconf plugin package (lwp) so the docs can be read in a browser. I'm inquiring on the shorewall-devel list about possible xinclude of the new shorewall man pages in our leaf-doc-set. Eric, Apparently, the Shorewall man page xml source isn't available via uri. XInclude isn't an option for us. -- Mike Noyes mhnoyes at users.sourceforge.net http://sourceforge.net/users/mhnoyes/ SF.net Projects: leaf, phpwebsite, phpwebsite-comm, sitedocs - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT business topics through brief surveys - and earn cash http://www.techsay.com/default.php?page=join.phpp=sourceforgeCID=DEVDEV ___ leaf-devel mailing list leaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/leaf-devel
Re: [leaf-devel] Documentation in Shorewall Configuration Files
Hi KP KP Kirchdoerfer wrote: Am Donnerstag, 23. November 2006 16:16 schrieb Erich Titl: But more important - there is no shorwall.lwp yet! And given the degree of complexity there may never be :-( I personally liked the documentation within the config files, as they provided most of what I always needed. I believe you always have a second machine around to use the pages from SF - most probably the machine from you have ssh'd into the router, I guess. Most of the time, a secnd machine, not always net access as the router to be configured may be the one targeted to provide this access, or even a bad shorewall configuration may cut net access. If you think one should be able to setup a LEAF router without net access and with self-contaning docs, we have to discuss adding all available docs to the images (except to the floppy) - and lynx. Sure, it was just an idea to provide something self contained. There is ample space on the CD image and I believe many people have some sort of flash media by now. cheers Erich - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT business topics through brief surveys - and earn cash http://www.techsay.com/default.php?page=join.phpp=sourceforgeCID=DEVDEV ___ leaf-devel mailing list leaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/leaf-devel
Re: [leaf-devel] Documentation in Shorewall Configuration Files
On Wed, 2006-11-22 at 09:10, Paul Traina wrote:
Mike Noyes wrote:
On Mon, 2006-11-20 at 11:30, Mike Noyes wrote:
We have a location in cvs for man pages, and output them daily for our
documentation build. All someone needs to do is add them to our
repository.
http://leaf.cvs.sourceforge.net/leaf/doc/man/ -- man page source
http://leaf-project.org/doc/man/ -- generated pdf and html using groff
Everyone,
We should probably update the BusyBox man page. Also, finding and adding
the dash man page is probably a good idea.
Other man pages are welcome there. Just add them to our cvs repository
and doc_build.sh will build them daily.
This should be done automatically, not by hand. Trying to maintain
multiple copies of this stuff by hand has created most of the mess we
see today.
Paul,
Agreed. Is the Shorewall man page made available as html/pdf? I think we
should link then.
doc-build.sh code used to convert man pages to html and pdf.
89 build_man () {
90 cd $TMP_DIR/doc/man
91 for f in *; do
92 groff -t -mandoc -Thtml $f $f.html
93 groff -t -mandoc -Tps $f $f.ps
94 ps2pdf $f.ps
95 rm $f.ps
96 done
97 }
I don't believe the BusyBox man pages are available on their site as
html/pdf. This might have changed, but it was the reason I placed the
man page in our repository.
--
Mike Noyes mhnoyes at users.sourceforge.net
http://sourceforge.net/users/mhnoyes/
SF.net Projects: leaf, phpwebsite, phpwebsite-comm, sitedocs
-
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT business topics through brief surveys - and earn cash
http://www.techsay.com/default.php?page=join.phpp=sourceforgeCID=DEVDEV
___
leaf-devel mailing list
leaf-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/leaf-devel
Re: [leaf-devel] Documentation in Shorewall Configuration Files
On Wed, 2006-11-22 at 09:09, Paul Traina wrote: Mike Noyes wrote: On Mon, 2006-11-20 at 10:22, Tom Eastep wrote: The documentation contained in Shorewall configuration files has always presented an upgrade dilema for users: Do I spend time merging the new documentation or do I put up with outdated documentation? In Shorewall 3.4, the documentation will be removed from the files and will be replaced by manpages. This presents a problem for users of embedded distributions like Bering-uClibc who typically don't have access to manpages. The current 3.3 test releases include the old documentation in a file named /etc/shorewall/Documentation. I would like to remove that file as it represents an additional copy of the documentation that must be maintained. I suggest that the Bering-uClibc build generate all of the man pages from manual 5 into a single /etc/shorewall/Documentation file. Tom, We have a location in cvs for man pages, and output them daily for our documentation build. All someone needs to do is add them to our repository. http://leaf.cvs.sourceforge.net/leaf/doc/man/ -- man page source http://leaf-project.org/doc/man/ -- generated pdf and html using groff Not Tom's job, but agree. Paul, Sorry. I didn't mean to imply it was Tom's or any of the Shorewall members responsibility. It is definitely something LEAF members should address. Tom, I apologize if you took my post in that manner. That's not what I intended. :-( -- Mike Noyes mhnoyes at users.sourceforge.net http://sourceforge.net/users/mhnoyes/ SF.net Projects: leaf, phpwebsite, phpwebsite-comm, sitedocs - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT business topics through brief surveys - and earn cash http://www.techsay.com/default.php?page=join.phpp=sourceforgeCID=DEVDEV ___ leaf-devel mailing list leaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/leaf-devel
Re: [leaf-devel] Documentation in Shorewall Configuration Files
On Wed, 2006-11-22 at 14:39, Mike Noyes wrote:
On Wed, 2006-11-22 at 09:10, Paul Traina wrote:
Mike Noyes wrote:
On Mon, 2006-11-20 at 11:30, Mike Noyes wrote:
We have a location in cvs for man pages, and output them daily for our
documentation build. All someone needs to do is add them to our
repository.
http://leaf.cvs.sourceforge.net/leaf/doc/man/ -- man page source
http://leaf-project.org/doc/man/ -- generated pdf and html using groff
Everyone,
We should probably update the BusyBox man page. Also, finding and adding
the dash man page is probably a good idea.
Other man pages are welcome there. Just add them to our cvs repository
and doc_build.sh will build them daily.
This should be done automatically, not by hand. Trying to maintain
multiple copies of this stuff by hand has created most of the mess we
see today.
Paul,
Agreed. Is the Shorewall man page made available as html/pdf? I think we
should link then.
doc-build.sh code used to convert man pages to html and pdf.
89 build_man () {
90 cd $TMP_DIR/doc/man
91 for f in *; do
92 groff -t -mandoc -Thtml $f $f.html
93 groff -t -mandoc -Tps $f $f.ps
94 ps2pdf $f.ps
95 rm $f.ps
96 done
97 }
Paul,
I believe, an even better solution is using DocBook XInclude from LEAF
to the Shorewall site. This is only possible if you're using DocBook XML
reference to generate man pages, and the docbook xml source is
available via uri.
--
Mike Noyes mhnoyes at users.sourceforge.net
http://sourceforge.net/users/mhnoyes/
SF.net Projects: leaf, phpwebsite, phpwebsite-comm, sitedocs
-
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT business topics through brief surveys - and earn cash
http://www.techsay.com/default.php?page=join.phpp=sourceforgeCID=DEVDEV
___
leaf-devel mailing list
leaf-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/leaf-devel
Re: [leaf-devel] Documentation in Shorewall Configuration Files
Mike Noyes wrote: I believe, an even better solution is using DocBook XInclude from LEAF to the Shorewall site. This is only possible if you're using DocBook XML reference to generate man pages, and the docbook xml source is available via uri. The only problem with that idea that I can think of, is that it vulnerable to Tom changing URLs or updating the documentation for Shorewall while we have not updated or changed ours. Up to you. - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT business topics through brief surveys - and earn cash http://www.techsay.com/default.php?page=join.phpp=sourceforgeCID=DEVDEV ___ leaf-devel mailing list leaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/leaf-devel
Re: [leaf-devel] Documentation in Shorewall Configuration Files
On Wed, 2006-11-22 at 14:50, Paul Traina wrote: Mike Noyes wrote: I believe, an even better solution is using DocBook XInclude from LEAF to the Shorewall site. This is only possible if you're using DocBook XML reference to generate man pages, and the docbook xml source is available via uri. The only problem with that idea that I can think of, is that it vulnerable to Tom changing URLs or updating the documentation for Shorewall while we have not updated or changed ours. Paul, A broken XInclude would fail validation. It shouldn't go longer than a day without notice. Also, our doc-build.sh script is robust enough to bail on error, and leave the current documentation alone. http://leaf.cvs.sourceforge.net/leaf/sourceforge/admin/doc-build.sh?revision=1.13view=markup Again, this is provided you have the docbook reference source available via uri. DocBook XInclude won't work otherwise. Note: this solution will provide LEAF a local current xslt-html version of the Shorewall docbook reference (man page). Up to you. Are you using DocBook v5, or 4.4? I haven't had time to learn the new v5 tool chain. The move to schema (RELAX NG) and XSLT 2 are both going to require considerable time/effort to learn properly. -- Mike Noyes mhnoyes at users.sourceforge.net http://sourceforge.net/users/mhnoyes/ SF.net Projects: leaf, phpwebsite, phpwebsite-comm, sitedocs - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT business topics through brief surveys - and earn cash http://www.techsay.com/default.php?page=join.phpp=sourceforgeCID=DEVDEV ___ leaf-devel mailing list leaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/leaf-devel
Re: [leaf-devel] Documentation in Shorewall Configuration Files
On Wed, 2006-11-22 at 16:56, Paul Traina wrote: Mike Noyes wrote: On Wed, 2006-11-22 at 14:50, Paul Traina wrote: Mike Noyes wrote: I believe, an even better solution is using DocBook XInclude from LEAF to the Shorewall site. This is only possible if you're using DocBook XML reference to generate man pages, and the docbook xml source is available via uri. The only problem with that idea that I can think of, is that it vulnerable to Tom changing URLs or updating the documentation for Shorewall while we have not updated or changed ours. Paul, A broken XInclude would fail validation. It shouldn't go longer than a day without notice. Also, our doc-build.sh script is robust enough to bail on error, and leave the current documentation alone. http://leaf.cvs.sourceforge.net/leaf/sourceforge/admin/doc-build.sh?revision=1.13view=markup Again, this is provided you have the docbook reference source available via uri. DocBook XInclude won't work otherwise. Note: this solution will provide LEAF a local current xslt-html version of the Shorewall docbook reference (man page). Up to you. Are you using DocBook v5, or 4.4? I haven't had time to learn the new v5 tool chain. The move to schema (RELAX NG) and XSLT 2 are both going to require considerable time/effort to learn properly. I don't do docbook at all. When I edited chapters, I just used an XML style editor and made good guesses as to what you guys needed. In the end, I think KP cleaned up a few tags. What troubles me more is that Tom updates the documentation on his site to represent the state of the art in shorewall v5, and the currently shipping versions of LEAF or BU are using shorewall v3, our documentation will not match the code we're shipping. snip Paul, This is another reason for keeping the man pages in our repository. We are sure to have the correct version used in leaf branches that way. Right now we are setup this way. Any change will require some type of effort. -- Mike Noyes mhnoyes at users.sourceforge.net http://sourceforge.net/users/mhnoyes/ SF.net Projects: leaf, phpwebsite, phpwebsite-comm, sitedocs - Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT business topics through brief surveys - and earn cash http://www.techsay.com/default.php?page=join.phpp=sourceforgeCID=DEVDEV ___ leaf-devel mailing list leaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/leaf-devel
