Re: Source code location?
> Adam Di Carlo wrote:
> >
> > In article <[🔎] m0zfCTv-000IiuC@polya>, jdg@maths.qmw.ac.uk (Julian Gilbey) writes:
> > >[Me]
> > >> Hmm. Interesting. So how do you use it? You *extend* the library?
> > >> Or you just read about it? ;)
> >
> > > [...] (In fact, it's so readable that it's
> > > been published as a book. Being written in CWEB means that you can
> > > create TeXable output from the source code, which can be
> > > pretty-printed.)
>
> My 'crucial questions' would be:
> - is the amount of documentation (prose) significantly larger
> than
> that of code (apparently, otherwise there would not be the
> book)
Compiled code = 300kb approx
Source code = 850 kb approx
Source code - comments/documentation = 240kb approx
The included documentation therefore accounts for the majority of the
source code.
> - what can be done without non-standard processing steps
> - can it be built with just make
> - can user read it without knowing literate programming,
> should there be a ready made html version available
Good questions. My intention was to provide the compiled libraries as
standard, along with the compiled demo programs, and to provide the
source code in addition as documentation.
Building requires CWEB in addition to make.
The code is not too difficult to read, but CWEB + TeX make it
beautiful.
> - what the installer expects to happen
> - since this is a binary package user must be prepared to have
> some binaries and documentation, but he [ha, ha!] is not
> necessarily expecting anything in /usr/src, it may be e.g.
> a link to separate partition, which is nearly full
> (I used to have this), and when the partition gets full your
> installation goes haywire
Aargh, I hadn't considered this problem.
> > Yes, I'm familiar with the concept of literate programming. Nice to
> > see a nice real world example. My *practical* objection w/ literate
> > programming is that programmers generally don't write the best
> > documentation. ;)
>
> Only rarely can a programmer, or anybody else, create
> documentation
> of such caliber that the same documentation is good for creating
> the
> software, maintaining it and using it. Also the maintainer has the
> added burden of having to consider the structure of both the
> documentation
> and the sw at the same time when doing changes.
However, experience has taught me, surprisingly, that it actually
turns out to be *easier* to maintain code like this than with
traditional models. It's also significantly easier for other people
to read and modify if it's well written than normal well-written
code. I point to TeX as a very good example: the very fact that we
now have a really good UN*X version of TeX (Karl Berry's web2c
system), the existence of extensions such as e-TeX, pdfTeX, Omega,
etc., is in no small part due to the ease of reading and understanding
such a complex, interwoven piece of software as TeX.
Of course, Knuth is no ordinary programmer! ;-)
> > >> My gut feeling would be under /usr/doc/sgb/examples, I suppose.
> >
> > > OK, I'll go for that, thanks. Would it be out of order to include a
> > > symlink /usr/doc/sgb/src -> /usr/doc/sgb/examples? I hope not.
> >
> > Sounds good to me... why not!
> >
> > Also, another ok suggestion: /usr/src/sgb, and symlink
> > /usr/doc/sgb/src -> ../../src/sgb
> >
> > It really come down to the "principle of least suprise".
>
> I would have the symlink the other way, create it in postinst,
> and silently accept if no link could be created
I think that's even better.
Back to the drawing board....
Julian
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Julian Gilbey Email: J.D.Gilbey@qmw.ac.uk
Dept of Mathematical Sciences, Queen Mary & Westfield College,
Mile End Road, London E1 4NS, ENGLAND
-*- Finger jdg@goedel.maths.qmw.ac.uk for my PGP public key. -*-
Reply to: