tags for protocols - examples

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Wed, Mar 15, 2000 at 08:31:28PM +0100 or thereabouts, Karl EICHWALDER wrote:
> dcm@redhat.com writes:
> 
> |   <systemitem class="resource"> would be my first choice
> 
> I don't think Telsa wants to talk about "systemitems" like FTP servers;
> she wants to talk about protocols.  <systemitem class="resource">SLIP</>?!?
> (for reference cf. Norman's book, p. 478ss.).
> 
> |   - but this
> |   question has come up before and is something that perhaps should be
> |   submitted as an RFE to the DocBook committee. The only place to really
> |   define protocols at the current time is in a <ulink> and I believe
> |   Telsa is trying to describe the protocol - not link to one... correct?
> 
> <ulink>s are for URLs etc., not for marking up protocols.
> 
> 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.
o ftp is a protocol.
o RealAudio is a protocol too, apparently!

     <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.

  <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).
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.

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 :)

Help!

Telsa