[lug] OT - Tech writing or Coding code.

[John Starkey]

Whoa. Man talking about Thanksgiving day generosity. Thanks. :} You really
went outta yer way. Very much appreciated.

I think <code> is what I remember seeing in 4.0 Unleashed. I'm wondering
if XHTML is gonna define a standard.

I'm somewhat limited with CSS. There's a JS style sheet I can't touch and
inline get's kinda whacky. Especially with NN. PERL (even if I had a
clue) would be outta the question also. Java, wonder if they've heard of
it :}. 

I did check some online resources like the source for www.cplusplus.com
and they're using <tt> so I stuck with that. But I'll do an extended find
and replace in HomeSite and use code, seems more logical.

The biggest problem though is taking his fifty different pseudo-styles
from the word doc and make it consistent (as you pointed out) without
insulting or mis-representing his points. Since it is an online course for
a Major Univ the whole point is to make it read like his lecture. So if he
itallicizes something is it because he's stressing a point or because it's
code and he forgot to use use arial (which holds the majority vote in his
lectures)?

"Industrial Strength Java" uses tt style code in the code samples but in
regular paragraphs he doesn't change the formatting. "Programming and
Problem Solving with C++" uses tt in both. I guess this is up to me and
since he made an attempt to make code in the paragraphs stand out I better
just <code> anything that isn't standard for that page. 

Thanks again.

John



> 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/
> 
> 
> _______________________________________________
> Web Page:  http://lug.boulder.co.us
> Mailing List: http://lists.lug.boulder.co.us/mailman/listinfo/lug
>