[elephant-devel] Documentation Build Problems and Questions

[Glenn Tarcea]

I'll take this list as a starting point and send out a list with  
items I know about. Areas I know I'd like to document a little more  
include just a tad bit more on using BDB (ie, parameters you can  
pass, and a reference to tell people to look at DB_CONFIG), as well  
as running multiple versions of Elephant (ie, Alex's ASDF registry  
example).

As a side note, I'm interested in helping out on the native lisp back  
end or the query system. I'm not sure what the next steps are, and I  
won't really have time to contribute more than documentation and  
tests until the middle of June.

Thanks,

Glenn

On May 26, 2008, at 9:42 AM, Ian Eslick wrote:

> 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
>
> _______________________________________________
> elephant-devel site list
> elephant-devel at common-lisp.net
> http://common-lisp.net/mailman/listinfo/elephant-devel
>
>