On 1 April 2015 at 11:08, Ralf Hemmecke <[email protected]> wrote: > On 03/31/2015 10:46 PM, Bill Page wrote: >> Code embedded in a lot of text, i.e. noweb, was bad enough but now we >> have a lot of text embedded in code and that seems even worse. > > Sorry, but I still think that writing literate programs is way better > than just writing code and pointing people to documents that are perhaps > inaccessible to the reader.
Why would these documents be inaccessible to the reader? If one is already editing a file named src/algebra/xhash.spad it is not hard to check for the existence of an associated file src/doc/algebra/xhash.tex (and or after installation, the same file in pdf or dvi format in an appropriate place). Even better: Why not provide a link to such documentation (if it exists) while browsing in Hyperdoc? > How would you have understood how XHashTable > works if I hadn't included all the background information and design > decisions? As I said, I do appreciate reading the background information and design decisions provided in your documentation, I just don't appreciate having it mixed up with the code itself. > And yes, separating code from documentation makes it easier > to have them diverge. > Sure. But as I see it the main consequence of the fact that the original Axiom open source project was fixated on Lisp and infatuated with literate programming is that basically after 15 years the developer documentation at the SPAD library level for Axiom or its forked projects remains woefully inadequate. Only a small fraction of the original code or even newly written code benefitted from a focus on this style of documentation. >> Although I do appreciate having the documentation available, but my >> first reaction was to start by deleting everything between )if >> LiterateDoc ... )endif so I could actually read the code in a >> reasonably concise form. > > That can be done by either an appropriate editor (would be nice if > someone convinces emacs to fold such parts) or a simple one-line-sed-script. > Of course stripping the documentation in this case was easy (but might not be so easy where )if false was present in the source code for other reasons). Concerning editors, I suppose that is part of my point: There are no good/standard tools for editing such mixed up source code and documentation. And more to the point, even if there were such tools it is doubtful that everyone who wants to contribute to FriCAS would agree to use them. >> Do we still have a way to produce pdf or dvi files from these >> "literate" source documents? > > See above. > Thanks. I think it would be nice if this was done during 'make' (or at least as an option of make) and the resulting pdf or dvi files were linked in Hyperdoc. Bill. -- You received this message because you are subscribed to the Google Groups "FriCAS - computer algebra system" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/fricas-devel. For more options, visit https://groups.google.com/d/optout.
