: Rowdy Blokland (rowdyb@dutiws.twi.tudelft.nl) wrote:

: :   I'm on the verge of documenting approximately 45 to 50 thousand lines of
: :   C++ code. Since softwaremodules have crosslinked relations by nature,
: :   using a hypertext tool seems like a fun and powerful idea to document
: :   the sourcecode.

I ran across something called UDT from Quadralay. I know nothing
about it -- it was merely a chance encounter -- but you may want
to check it out. See http://www.quadralay.com.

--
Glenda Jeffrey                                     Email: jeffrey@hks.com
Hibbitt, Karlsson & Sorensen, Inc                  Phone: 401-727-4200
1080 Main St.
Pawtucket, RI 02860

In article <Czspq2.8q7@dutiws.twi.tudelft.nl>,
rowdyb@dutiws.twi.tudelft.nl (Rowdy Blokland) wrote:

>   I'm on the verge of documenting approximately 45 to 50 thousand lines of
>   C++ code.
>
>   Well, the trouble is: Hyperlinks to another documents page- and linenumber
>                         work fine, but software is subject to change during
>                         its whole lifecycle!
>                         This renders these type of links useless.
>                         And God, I need them badly.
>
>   QUESTION: * Who knows of any solution to this one?
>             * Who would happen to have programmed some tiny tool to
>               fix this?   (I mean, come on, you could simply jump
>                            to a (possibly unique) word, for example)
>

If you're using Windows, you might want to try my  "Interactive Cross
Reference for Windows".    I wrote it the a while ago to solve a similar
problem with understanding large project source file.. This utility will
build a cross reference database from any complex C/C++ project such as
MFC's source code and all its samples.  After the project is built, the
programmer can quickly browse/cross reference any symbols, variables,
functions in the project interactively and instantly.

I designed this program to be FAST and function as an "Interactive Grep".
My program can cross reference any text file such as resource text files
and Visual basic text files, not just C/C++ code.

You can ftp the program from
oak.oakland.edu:/pub/msdos/windows/ixfw2_1b.zip, or download
"ixfw2_1b.zip" from CompuServe: Library/Utilities section of MSLAND forum.



-Tony

Rowdy Blokland (rowdyb@dutiws.twi.tudelft.nl) wrote:

:   I'm on the verge of documenting approximately 45 to 50 thousand lines of
:   C++ code. Since softwaremodules have crosslinked relations by nature,
:   using a hypertext tool seems like a fun and powerful idea to document
:   the sourcecode.

On NEXTSTEP, the C++ compiler supports Rich Text Format (RTF) code,
which is just stripped away for the compile by a preprocessor.
This allowed links (based on hiddel labels) and RTF formatted
code.  I wrote a program (RTFSyntax) that formatted the code using
regular expressions.  The only thing it was missing was the capability
of including graphics and sound (though you could link to them).

Ross.

In article <Czspq2.8q7@dutiws.twi.tudelft.nl> rowdyb@dutiws.twi.tudelft.nl (Rowdy Blokland) writes:
>
>  I'm on the verge of documenting approximately 45 to 50 thousand lines of
>  C++ code.

 Better you than me.

>  Well, the trouble is: Hyperlinks to another documents page- and linenumber
>                        work fine, but software is subject to change during
>                        its whole lifecycle!
>                        This renders these type of links useless.
>                        And God, I need them badly.
>
>  QUESTION: * Who knows of any solution to this one?

 Use a literate programming system.

>  so ANY tips wrt this, vaguely related ideas on hyperdocumenting
>  source code of any kind, and bad poetry is MORE than welcome !

 Generate the document FROM the source code. Do not write
separate doco.

--
        JOHN (MAX) SKALLER,         INTERNET:maxtal@suphys.physics.su.oz.au
 Maxtal Pty Ltd,
        81A Glebe Point Rd, GLEBE   Mem: SA IT/9/22,SC22/WG21
        NSW 2037, AUSTRALIA     Phone: 61-2-566-2189

In article <Czv5ou.Mzv@ucc.su.OZ.AU>,
                John Max Skaller <maxtal@physics.su.OZ.AU> wrote:

>In article <Czspq2.8q7@dutiws.twi.tudelft.nl> rowdyb@dutiws.twi.tudelft.nl (Rowdy Blokland) writes:
>>
>>  I'm on the verge of documenting approximately 45 to 50 thousand lines of
>>  C++ code.
>
> Better you than me.
>
>>  Well, the trouble is: Hyperlinks to another documents page- and linenumber
>>                        work fine, but software is subject to change during
>>                        its whole lifecycle!
>>                        This renders these type of links useless.
>>                        And God, I need them badly.
>>
>>  QUESTION: * Who knows of any solution to this one?
>
> Use a literate programming system.
>
>>  so ANY tips wrt this, vaguely related ideas on hyperdocumenting
>>  source code of any kind, and bad poetry is MORE than welcome !
>
> Generate the document FROM the source code. Do not write
>separate doco.
>

Erm, could HTML commands be reasonably embedded? - ie links? You could
then view the docs on an HTML browser...

Just a thought ;-)

--
Adam

=======================================================================
| Computech  Tel/Fax: 0181 673 7817  email: adam@comptech.demon.co.uk |
=======================================================================

In article <Czv5ou.Mzv@ucc.su.OZ.AU>, maxtal@physics.su.OZ.AU (John Max Skaller) writes:
> In article <Czspq2.8q7@dutiws.twi.tudelft.nl> rowdyb@dutiws.twi.tudelft.nl (Rowdy Blokland) writes:

> >  I'm on the verge of documenting approximately 45 to 50 thousand lines of
> >  C++ code.
> ...
> >  Well, the trouble is: Hyperlinks to another documents page- and linenumber
> >                        work fine, but software is subject to change during
> >                        its whole lifecycle!
> >                        This renders these type of links useless.
> >                        And God, I need them badly.
> >
> >  QUESTION: * Who knows of any solution to this one?

You are too late.

You built the house.  _NOW_ you want a set of plans for it?

Your documentation should be a written (or graphical, or otherwise
explicit, recorded) design.

>  Use a literate programming system.
 ...
>  Generate the document FROM the source code. Do not write
> separate doco.

I'd say that you should write the source code to match the design, which
should exist first.  Ideally, each clause in the design would have a
hyperlink into the code, and vice-versa.

And, of course, each component is under change control, and the whole
system is under version control (which maintains consistent _sets_ of
changes).
--
 (This man's opinions are his own.)
 From mole-end    Mark Terribile
 mat@mole-end.matawan.nj.us, Somewhere in Matawan, NJ

In article <19941127.001508.80@comptech.demon.co.uk> adam@comptech.demon.co.uk writes:
>> Generate the document FROM the source code. Do not write
>>separate doco.
>>
>
>Erm, could HTML commands be reasonably embedded? - ie links? You could
>then view the docs on an HTML browser...

 I don' t know. But if you invent a special kind of
comment, you can then compile the code -- and also
pre-process it to create any kind of document you want,
and _then_ view it. Perhaps the extra step is a pain -- but
its better than writing a completely separate document.

 For an example of literate programming using Funnel Web,
see CH13 in "Software solutions in C". Its been retypeset,
but basically its the actual code I compiled and tested.

 FW is a flat format (paper document oriented),
not hypertext -- but similar principles could be applied.

 I also have a reference manual generator, that
will document any set of libraries, including an alphabetic
class listing with inheritance diagrams for every class.
Using a specific commenting style and //$$ comments
provides typeset, structured output -- with arbitrary
tables and graphics embedded (as postscript :-)

 I would like to upgrade the program to support
browsing -- and then grammar based editing (but I probably
will never get around to it :-)


--
        JOHN (MAX) SKALLER,         INTERNET:maxtal@suphys.physics.su.oz.au
 Maxtal Pty Ltd,
        81A Glebe Point Rd, GLEBE   Mem: SA IT/9/22,SC22/WG21
        NSW 2037, AUSTRALIA     Phone: 61-2-566-2189

In article <19941127.001508.80@comptech.demon.co.uk>,
adam@comptech.demon.co.uk wrote:

> >>  Well, the trouble is: Hyperlinks to another documents page- and linenumber
> >>                        work fine, but software is subject to change during
> >>                        its whole lifecycle!
> >>                        This renders these type of links useless.
> >>                        And God, I need them badly.
> >>  Well, the trouble is: Hyperlinks to another documents page- and linenumber
> >>                        work fine, but software is subject to change during
> >>                        its whole lifecycle!
> >>                        This renders these type of links useless.
> >>                        And God, I need them badly.

That's the problem I looked at in my MSc, although not at the level of
code - I was interested in maintaining the links between design decisions:
the factors affecting the design decisions, how to view the impact of a
change to one part of the design, etc.  In principle you seem to have the
same problem.
   It's impossible to know what changes will occur in the future.
Basically, the more links you have, the more links that need to be
maintained, so it's an escalating problem.  Principle 1, therefore, should
be to minimise the number of links. Remember, traceability isn't the
answer, it's the problem.  We don't want traceability, because
traceability means complexity.
   I think that the links must be given equal status as the code.  If you
see links, as the "extra bit" to help in maintenance, then you're not
going to get too far, is my feeling.
   One other thing.  I found that designers were too apt to rely on the
links when making changes/finding bugs.  That is, if someone else had
constructed a link, they were willing to accept the link's validity.  So,
beware of leading people down the path of relying on your links...the
links may be bugged aswell.
   Sorry to be a bit pessimistic.  I think that links are essential for
the controlled evolution of software, but they're not the whole answer.
Good luck.

F.Hamilton

In article <1994Nov26.150100.28327@mole-end.matawan.nj.us>,
mat@mole-end.matawan.nj.us wrote:

> You are too late.
>
> You built the house.  _NOW_ you want a set of plans for it?
>
> Your documentation should be a written (or graphical, or otherwise
> explicit, recorded) design.
> I'd say that you should write the source code to match the design, which
> should exist first.  Ideally, each clause in the design would have a
> hyperlink into the code, and vice-versa.
>
> And, of course, each component is under change control, and the whole
> system is under version control (which maintains consistent _sets_ of
> changes).

You're absolutely right, Mat, but that doesn't help the guy above.
There's so much undocumented code that's lying around it's a nightmare to
even consider maintaining it.  But maintained it must be.  Having a
hyperlink from the design to the code is ideal, but unlikely to be
possible in most cases.  A design decision will affect code all over the
place.  The decision to "use a menu based user interface" will have many
hyperlinks coming from it, going into the code.  But I accept you're
suggestion in principle.  Implementing and maintaining the links is
another matter.

F.Hamilton

In article <19941127.001508.80@comptech.demon.co.uk> adam@comptech.demon.co.uk (Adam Goodfellow) writes:
>From: adam@comptech.demon.co.uk (Adam Goodfellow)
>Subject: Re: Hyperdocumenting C++ Code (HyGEN)
>Date: Sun, 27 Nov 1994 00:15:08 GMT

>>>  Well, the trouble is: Hyperlinks to another documents page- and linenumber
>>>                        work fine, but software is subject to change during
>>>                        its whole lifecycle!
>>>                        This renders these type of links useless.
>>>                        And God, I need them badly.
>>>
>>>  QUESTION: * Who knows of any solution to this one?
>>
>>       Use a literate programming system.
>>
>>>  so ANY tips wrt this, vaguely related ideas on hyperdocumenting
>>>  source code of any kind, and bad poetry is MORE than welcome !
>>
>>       Generate the document FROM the source code. Do not write
>>separate doco.
>>

>Erm, could HTML commands be reasonably embedded? - ie links? You could
>then view the docs on an HTML browser...

There's a package called c++2html floating around someplace. It's based on an
earlier package that converted c++ to latex---c++2latex. I don't recall the
ftp site I grabbed them from, but I think archie should be able to find one or
both.

Mike.

In article <CzxFxI.54t@ucc.su.OZ.AU> maxtal@physics.su.OZ.AU (John Max Skaller)
writes:

    For an example of literate programming using Funnel Web,
   see CH13 in "Software solutions in C". Its been retypeset,
   but basically its the actual code I compiled and tested.

    FW is a flat format (paper document oriented),
   not hypertext -- but similar principles could be applied.

I am the current (unofficial) FunnelWeb maintainer, and I have a beta
version that generates HTML with hyperlinks, if anyone is interested
in joining the beta list.
      Cheers,
        Tony.
--
_____________________________________________________________________________
A.B.Coates, Dept. of Physics,
The University of Queensland  QLD  4072  Australia.
Email: coates@physics.uq.oz.au
Phone: (07/+617) 365-3424  Fax: (07/+617) 365-1242
Disclaimer: The University is ignorant of my
            opinions, let alone guilty ...
_____________________________________________________________________________

  I'm on the verge of documenting approximately 45 to 50 thousand lines of
  C++ code. Since softwaremodules have crosslinked relations by nature,
  using a hypertext tool seems like a fun and powerful idea to document
  the sourcecode.

  The tool I'm using is named HyGEN.

  So what, you think.
  Have a happy life.

  Well, the trouble is: Hyperlinks to another documents page- and linenumber
                        work fine, but software is subject to change during
                        its whole lifecycle!
                        This renders these type of links useless.
                        And God, I need them badly.

  QUESTION: * Who knows of any solution to this one?
            * Who would happen to have programmed some tiny tool to
              fix this?   (I mean, come on, you could simply jump
                           to a (possibly unique) word, for example)

  It has rumour that the author of HyGEN is deaf to this type of criticism,
  and actually I can sum up a few more link-suggestions I'd really
  want to see implemented,
  so ANY tips wrt this, vaguely related ideas on hyperdocumenting
  source code of any kind, and bad poetry is MORE than welcome !

  Thanks in advance,
  Cheers,
  RowdyB
  Delft University of Technology

Rowdy Blokland <rowdyb@dutiws.twi.tudelft.nl> wrote:
>  I'm on the verge of documenting approximately 45 to 50 thousand lines of
>  C++ code. Since softwaremodules have crosslinked relations by nature,
>  using a hypertext tool seems like a fun and powerful idea to document
>  the sourcecode.
>
>  Well, the trouble is: Hyperlinks to another documents page- and linenumber
>  work fine, but software is subject to change during
>  its whole lifecycle!  This renders these type of links useless.
>  And God, I need them badly.

 I've never used the HyGEN tool, but C/C++ to HTML converters have
been created.  I believe they are written in PERL.  If you are feeling
especially crafty, it would be possible to devise a PERL script that would
do translation of your C++ code on the fly.  That would get over the
problem of dynamically changing code.  Depending on what you mean by
hyperdocumentation, that may be the best bet.

#include <standard_disclaimer.h> // I speak from experience, not authority

  Jeffrey Hobbs    Univ of Oregon CIS grad student
  Associate, NBOC         email: jhobbs@cs.uoregon.edu
  URL: http://www.cs.uoregon.edu/~jhobbs/