RE: tags for protocols - examples

[Gregory Leblanc <GLeblanc cu-portland edu>]

I know even less about DocBook than Telsa, so I'll stick to "technical"
issues.  Just a couple of them below.

> -----Original Message-----
> From: Telsa Gwynne [mailto:hobbit@aloss.ukuu.org.uk]
> Sent: Tuesday, March 21, 2000 6:23 AM
> To: Gnome Doc List
> Subject: tags for protocols - examples
> 
> > But before it gets too academic, Telsa, please post a short 
> example with
> > context -- maybe, I'm completely wrong ;-)
> 
> Sorry for the delay. Blame Paris :)
> 
> Examples are copious in gnome-lokkit/doc/C/gnome-lokkit.sgml and 
> occasional in some of the monitor applet docs.
> 
> gnome-lokkit: Alan wrote the initial stuff and I marked up some more. 
> Alan is happy with it as it is as he thinks people who use 
> gnome-lokkit
> are more likely to understand program names rather than 
> protocols. (So 
> please don't go changing the CVS version without notice, he 
> says.) But 
> it does have some great examples of things I haven't marked up 
> properly:
>      <para>
>        The high-security option blocks all incoming 
> connections to your 
>        machine except for a few basic services which you get 
> to select. 
>        This gives  maximum coverage for security but will stop 
>        <application>IRC</application> DCC sessions completely and 
>        <application>ICQ</application> from working without a 
> proxy. It will 
>        also affect <application>ftp</application> and 
> <application>realaudio
>        </application>, although these can be set up to work 
> in this mode via 
>        the <guilabel>preferences dialogues</guilabel>.
>      </para>
> 
> o IRC isn't really an application. 
> o dcc is an irc function.

Yep.

> o ftp is a protocol.
> o RealAudio is a protocol too, apparently!

Actually, ftp is an application, as is RealAudio.  (ever typed in 'ftp' at
the command line?)  They are also protocols.  Sorry, I just had to make
things more interesting.

> 
>      <para>
>        The low security mode screens only system sevices 
> (including your 
>        X windows sessions and NFS) from the outside world. 
> This will not 
>        generally interfere with other facilities such as ICQ 
> and Realaudio.
>      </para>
> 
> o NFS is a filename, a protocol, a service, possibly a trademark, and
> more. filename and trademarks are the only sorts I can find tags for,
> and in this case services or protocols would be better.

I think "filesystem" and not "filename", since filename is a little too
generic.  I thought that there was some markup for filenames, such as in
examples of things to type, etc.  Maybe not...

> 
>   <para>
>     Realaudio defaults to using UDP which is hard to firewall. If you 
>     bring up your <guilabel>Realaudio preferences</guilabel> you can 
>     change the stream type to 'TCP'. This will allow you to 
> continue to 
>     use the Realaudio service.
>   </para>
> 
> o UDP and TCP/IP are protocols (and yes, "TCP" is deliberate in the
> text, as that's what the realaudio preferences have).

TCP/IP is a suite of protocols.  User Datagram Protocol (UDP) is part of
that suite, as are Transport Control Protocol (TCP, and Internet Control
Message Protocol (called ICMP or, incorrectly, ping).  There are actually
quite a few others, but those are the ones that get about 99.99999% of
internet traffic, so we need not worry about the others.  I won't bore you
with details, but I think that we do need some sort of markup for protocols.
Part of me wants to CC this to the docbook list and see if Norm has any
thoughts, but maybe we'll get a few more ideas out here first.

> o Realaudio here is apparently a program, but it might be the protocol
> in general. (I know nothing about it.)
> 
> Enough examples? :) I am justifying this rather dodgy attempt 
> at markup 
> on the "Alan wanted them to be clearly shown as programs and 
> applications in the help" basis :) But in other 
> circumstances, referring 
> to ftp, udp and tcp/ip with better tags might be necessary.
> 
> An example is in the multiload applet stuff, for netload, 
> which doesn't
> yet appear to be in CVS, but Jacob said he'd got them:
>        <para>
>          SLIP is the serial line IP protocol. It is not commonly used
>          any more, being largely replaced by PPP, but it is one way of
>          connecting a computer to other machines which was popular for
>          modems.
>        </para>
> ...
>        <para>
>          Other forms of networking are available, such as ways to
>          talk over infra-red beams (IRDA), ways to talk over amateur
>          radio (AX.25), and token-ring networks. Anything the applet
>          finds which is not SLIP, PPP or ethernet is monitored under
>          'other'.
>        </para>
> 
> In that context, I didn't think <application> was a very good idea.

Agreed, in that context it referrs to the FTP protocol, and not the FTP
application.:-/

> 
> And on a related note (from gnome-lokkit), whilst I am displaying
> my ignorance:
> 
>     <para>
>       You need to have a Linux kernel with IPFW or IPChains enabled:
> 
> o Dunno what IPFW or IPChains should be :)

If you markup the word "Linux" with anything special, then they should
probably be marked up in the same way.  "IPFW" and "IPChains" mean nothing
(to me) when not associated with a specific set of code in the Linux Kernel
source.
So, almost nothing about DocBook in there, but anybody who reads those two
messages should have a pretty good idea what Telsa, and the rest of the GDP
team, and pretty soon people from the LDP and OSWG, are facing from a point
of marking up some applications.  This may require customization of the DTD,
and as such, customization of the stylesheets.  DocBook gurus, have at it!
	Greg