[lug] OT - Tech writing or Coding code.

[Tkil]

no real "standard" to point at, but a few comments:

don't think in terms of "teletype" or "arial".  use content-based
markup (e.g. <code>, <blockquote> etc).  never use <font>; it's an
abomination.

if you want to be really swank, use CSS.  depends on what your target
browsers are, tho; NS4 support for CSS is iffy at best.

generally, i'd use <code> inside paragraphs, maybe switching to <pre>
inside <blockquote> for longer samples.  there are a few other tags
(such as <var>, <kbd>, and <samp>) which, if they were well supported,
would be valuable here; but since they're not, oh well.

you might also investigate docbook and/or the linux-doc SGML DTD.
(although i believe the latter is being phased out in favor of the
former).  both of these drastically reduce your options, and that is a
*good* thing.

note that it's reasonable to use <tt> for stuff that is supposed to
typed or displayed.  so i'd be fine with this sort of use:

  <blockquote>
    <tt>
      Enter password: <b>open seasame!</b><br>
      Denied!
    </tt>
  </blockquote>

you can add CSS to this if you like.  i marked up a data transfer
standard with tags like this:

  <tt class="field-name">REFERENCE_DT</tt> is an eight-digit field
  which must be in this format: <tt class="format">YYYYMMDD</tt>

and so on.  the generic tag for this is <span>, but that's not as well
supported yet, alas.

consider using a documentation system that integrates with the
language you're describing, so that you can have the examples and the
documentation in the same file and be able to test it easily.  systems
such as Perl's POD, Java's JavaDoc, Python's function descriptors
(what are those really called?) etc.  C++ doesn't have one that is
quite that tightly coupled with the language, but there is "doxygen"
which seems to provide much of the functionality of JavaDoc for C++
and related languages.

one last suggestion: be consistent, and use tags that you can easily
search for later and replace.  you might even go so far as to "invent"
your own markup, and then translate it into whatever output format you
really want.  (a new markup language is probably too drastic, but it's
a way to have the original content have full semantic meaning with
<var> and whatnot, but still translate it into a format that most
browsers can accept and display sensibly.)

t.

p.s. as for examples, i'm not sure what to suggest.  i have an article
     from the perl journal that i marked up in HTML; it's not very
     fancy, but it's something to look at:

        http://slinky.scrye.com/~tkil/perl/spider.html

     Tigran Aivazian from the linux-kernel list did a fascinating
     series of pages on the guts of 2.4-to-be, and it should have lots
     of code snippits in it.  not sure what his style is, but it's
     something to look at:

        http://www.moses.uklinux.net/patches/lki.html

     a more raster-graphics approach was used by Gisle Aas in his
     "PerlGuts Illustrated":

        http://gisle.aas.no/perl/illguts/

     finally, take a look at the C and C++ FAQs, which talk a lot
     about bits of code.  again, i haven't looked at their style, but
     they've both been around for a while.  just took a look at the
     C++ FAQ; it's pretty nice.

        http://www.eskimo.com/~scs/C-faq/top.html
        http://new-brunswick.net/workshop/c++/faq/