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 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.php&p=sourceforge&CID=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: > 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. 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. -Tom -- Tom Eastep\ Nothing is foolproof to a sufficiently talented fool Shoreline, \ http://shorewall.net Washington USA \ [EMAIL PROTECTED] PGP Public Key \ https://lists.shorewall.net/teastep.pgp.key - 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.php&p=sourceforge&CID=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.php&p=sourceforge&CID=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
KP Kirchdoerfer wrote: > Am Donnerstag, 23. November 2006 16:16 schrieb Erich Titl: > > Hi Erich; > >> 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. > > Given we add it those our manpages a shorwall.lwp can be enhanced to include > the link; but then, if you can browse to the router and access a link from > there to the net, you can also directly browse to the SF pages. > > But more important - there is no shorwall.lwp yet! > > >> 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. I personally would just convert the man pages to plain text (as previously discussed), package them separately from the shorewall scripts (ie: swdoc.lrp or somesuch), and make them available via the 'help' command (which I believe should still work in the current Bering based distos). Side-note: Does anyone actually ever use the help command?!? A fancier alternative would be to make a simple 'man' command that would require man pages be in plain text format (ie: very similar to the current 'help' command, but would automatically find man files in their more normal locations). This would require pre-processing all man pages, but that shouldn't be too big a deal on a typical build system. It also ought to be possible to use bash/sed or similar and do the man page -> plain text processing via a script directly on the leaf box (ie: a lightweight man command), not that I'm volunteering or anything! :) -- Charles Steinkuehler [EMAIL PROTECTED] - 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.php&p=sourceforge&CID=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
Am Donnerstag, 23. November 2006 16:16 schrieb Erich Titl: Hi Erich; > 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. Given we add it those our manpages a shorwall.lwp can be enhanced to include the link; but then, if you can browse to the router and access a link from there to the net, you can also directly browse to the SF pages. But more important - there is no shorwall.lwp yet! > 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. 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. kp - 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.php&p=sourceforge&CID=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
Am Donnerstag, 23. November 2006 19:42 schrieb Mike Noyes: > 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. Ok, it's not a big deal once the leaf-set-xml has been adjusted to upload the man pages into leaf/doc/man. They will be in the sources; and can be added to cvs together the buildtool setups. kp - 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.php&p=sourceforge&CID=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 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.php&p=sourceforge&CID=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 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.php&p=sourceforge&CID=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 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. > > > The post by Tom to you made me believe Shorewall man pages were > available for current Bering-uClibc releases. > You copied the wrong part :-) 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." Eric > > -Forwarded Message- > From: Tom Eastep <[EMAIL PROTECTED]> > To: Eric Spakman <[EMAIL PROTECTED]> > Cc: Leaf Development > 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 /manpages/*.5; do man -l $file | col > -bx >> Documentation > done > > -Tom > > > -- > Mike Noyes > 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.php&p=sourceforge&CID=DEVDEV > > > ___ > leaf-devel mailing list leaf-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/leaf-devel > > - 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.php&p=sourceforge&CID=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.php&p=sourceforge&CID=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 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 /manpages/*.5; do man -l $file | col -bx >> Documentation done -Tom -- Mike Noyes 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.php&p=sourceforge&CID=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.php&p=sourceforge&CID=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 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.php&p=sourceforge&CID=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. >>> >>> >>> >> 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.php&p=sourceforge&CID=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. >> >> > 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.php&p=sourceforge&CID=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. > > 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 - 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.php&p=sourceforge&CID=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 > >>> 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.13&view=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. 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 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.php&p=sourceforge&CID=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 > > 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.13&view=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 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.php&p=sourceforge&CID=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 > 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.php&p=sourceforge&CID=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
to generate man pages, and the docbook xml source is
available via uri.
--
Mike Noyes
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.php&p=sourceforge&CID=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 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.php&p=sourceforge&CID=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
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.php&p=sourceforge&CID=DEVDEV
___
leaf-devel mailing list
leaf-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/leaf-devel
