Subject:
Re: howto creation
From:
Tabatha Persad ####@####.####
Date:
19 Aug 2002 03:16:15 -0000
Message-Id: <1029716102.8430.354.camel@mysticchild.dbsoftware.com>
Hi Charles!
On Sun, 2002-08-18 at 21:38, xterminus wrote:
> Hi all!
>
> I'm a long-time user and fan of the linux LDP, especially the HOWTO's.
They have often served me a great introduction into new subjects, and I
can't count the times a hint or an idea suggested in any one of them has
helped me out of a jam. It's a valuable resource, and I'd like to give
a little back ;)
>
> The reason for this post is because I'm thinking about sitting down
and putting together a HOWTO. Specificly, I wrote several pages of
notes down and gave a presentation to my LUG recently on how to
implement IPSEC tunneling using FreeS/WAN. I've got plenty of materials
to draw on, but I've never seen a good guide for new users on the
subject, and most of the requests for help that I see on the freeswan
mailing lists are pretty basic in nature and reflect the huge learning
curve involved in learning about ipsec tunneling.
>
> What mention I see in the existing howto's (VPN-HOWTO,
VPN-Masquerade-HOWTO) either cover different techonologies, or do not
cover just getting an ipsec tunnel up and running.
>
> I would also like to fill in some of the blanks in both of those
related HOWTO's as well, assuming the authors (John D. Hardin and
Matthew D. Wilson) are taking submissions. (I'll be firing a personal
email off to both of you shortly)
I did some work with Matthew Wilson with the VPN HOWTO recently, and I'm
sure you'll hear from him, he was very nice to work with!
Some other documents that mention tunnels:
MindTerm-SSH-HOWTO
Remote Bridging with IP Tunnels mini-HOWTO
Linux IPv6 HOWTO
Linux IPX-HOWTO
IP-Masquerade-HOWTO
Linux Advanced Routing & Traffic Control HOWTO
Securing and Optimizing Linux RedHat Guide
Now keep in mind, only a few mention ipsec tunnels. I wanted you to
know about these because it doesn't hurt to research the subject, just
in case! If you haven't checked these out yet, I would, to see if there
is anything there.
>
> In any case, the documentation that exists, (mainly the FreeS/WAN
website) is pretty comprehensive, and frankly is a little mind-boggling
in scope. It covers pretty much every possible scenario one could think
of.
>
> I would like to take a stab at presenting it in a human-readable
manner.
Your email demonstrates that you are very well-spoken and literate. I
bet you'd do a great job! I think that if you want to create a HOWTO
that uses another type of technology, just make that clear in your
title, so it is not confused with related titles.
> I've read a bit about DocBook, and LinuxDoc, and it wasn't made which
one was the appropriate format to begin to use. (I have zero background
in both, but the syntax seems similar to xhtml). LinuxDoc seems to a
bit easier to approach - is this the preferred way of starting? Or
should I just learn DocBook (which seems far more complex)?
>
> In general, I don't mind extra complexity, but in this case I'd rather
spend my time researching and writing rather than learning yet another
syntax. Is linuxdoc still acceptable?
I doubt anybody would say LinuxDoc is not acceptable, as it is
definitely appropriate for certain projects. Consider the scope and
size of your document and what types of elements you need to include.
If you want to include graphics, you may consider DocBook. Although
DocBook can seem comprehensive, it's that way for a reason
Docbook XML 4.1.2 is my best friend now. I find the Openjade tools work
really well, and output comes out looking pretty snazzy. You can find a
great HOWTO at www.jimweller.net for getting the tools installed
correctly on a Linux system. If followed correctly, your tools will
work. The DocBook definitive guide shows how to use the tags, and if
you use Emacs with psgml, you get all sorts of extra goodies to help you
(which I can't rave enough about)!
>
> Now that I've broached the subject here, what's the next step? I
figure it's just to sit down and start to put together a formal outline
start writing. Are they're any gotchas I should be aware of before I
start?
>
Well, remember that one "gotcha" on graphics. I would suggest if you
think that the HOWTO would be comprehensive, the way DocBook sections
things out makes for great copy. I'm really not trying to advocate one
way or the other, but I find it more robust and kind of like that about
it.
I would go ahead and create an outline. See what folks think! If you
want some advice or help with the tools, just fire off an email and I'll
see what I can do to help!
> Anyway, thanks for listening. I'm looking forward to getting this
project done - and beyond. ;)
>
With that kind of enthusiasm, how could anybody say no? :)
Cheers!
--
Tabatha Persad
Web: www.merlinmonroe.com
Linux Documentation Project Editor (http://www.tldp.org)
Gnu Writing Movement Contributor (http://gwm.gnu.org)
Linux Counter Area Manager US:wa (http://counter.li.org)
