[elephant-devel] Documentation Build Problems and Questions

[Ian Eslick]

Thanks Glen,

Some of these are issues caused by a change in the APIs in unstable -  
I haven't built the documentation locally in quite some time.  I'll  
probably need to change some of the docs to accommodate this (like the  
class indexing section).

Not sure about the png/pdf problem, but if the change you made works -  
then just do it again using 'darcs mv' so the source control gets the  
message.

If you can get it to work for you so you can work on the documentation  
content, that should be enough for now.  Robert or I can sit down with  
you and hash through this when some time opens up.

One thing that would be helpful is putting together a TODO list that  
identifies the things that need to be documented or fixed:

1) Update all class indexing docs, especially derived indices (dropped  
explicit API, hierarchical indexed slots)
2) Document new slot options in defpclass
3) Document associations
4) Document cached operation
5) Revamp database synchronization
6) Discussion of upgrade and schemas
7) Add section for postmodern backend
8) section on multi-threaded testing and update testing section in  
general
9) Update 'multi-threading' considerations
10) Maybe a section on building the docs!  :)

Ian

On May 25, 2008, at 10:33 PM, Glenn Tarcea wrote:

> I have a few questions on the document builds. I've finally  
> completed a build of the documentation, including generating a PDF  
> file, but I had to change a few files to get the document build to  
> complete. Having not used TeX before, and because I hacked things to  
> get it working, I'm going to describe my changes, rather than send  
> out an incorrect patch.
>
> The first issue I ran into was that makeinfo was failing. I was able  
> to resolve that by removing the following includes in the  
> reference.texinfo file:
>
> @subsection Direct Class Index Manipulation
>
> @include includes/fun-elephant-find-class-index.texinfo
> @include includes/fun-elephant-find-inverted-index.texinfo
> @include includes/fun-elephant-make-class-cursor.texinfo
> @include includes/macro-elephant-with-class-cursor.texinfo
> @include includes/fun-elephant-make-inverted-cursor.texinfo
> @include includes/macro-elephant-with-inverted-cursor.texinfo
>
> and
>
> @subsection Dynamic Indexing API
>
> @include includes/fun-elephant-enable-class-indexing.texinfo
> @include includes/fun-elephant-disable-class-indexing.texinfo
> @include includes/fun-elephant-add-class-slot-index.texinfo
> @include includes/fun-elephant-remove-class-slot-index.texinfo
> @include includes/fun-elephant-add-class-derived-index.texinfo
> @include includes/fun-elephant-remove-class-derived-index.texinfo
>
> Next, I tried to build the PDF file, but I kept getting pdfetex  
> failures. It couldn't find the 'image' file IndexedBtrees1.pdf and  
> ArchDiagram.pdf. The file user-guide.texinfo refers to  
> IndexedBtrees1, but it it (correctly) referring to the png file. The  
> same with the ArchDiagram reference in elephant-design.texinfo. If I  
> copy the IndexedBtrees.png file to IndexedBtrees.pdf and  
> ArchDiagram.png to ArchDiagram.pdf then the system completes.
>
> The @image commands look correct (example:
> @image{ArchDiagram,,4.5in,[Architecture Diagram],png})
>
> Even if I change the ",png" to ",.png" that doesn't make a  
> difference, it is still looking for a .pdf file.
>
> Is anyone else able to build the documentation, without having to  
> rename the .png files to .pdf files? I'm building on MacOSX (Tiger).  
> Right now I don't have access to another system to try this on, but  
> I am wondering if there is an issue with my pdfetex command not  
> correctly parsing the @image.
>
> Thanks,
>
> Glenn
>
>
> _______________________________________________
> elephant-devel site list
> elephant-devel at common-lisp.net
> http://common-lisp.net/mailman/listinfo/elephant-devel