bugCERTI - Bugs: bug #20850, Install documentation incomplete

 
 

bug #20850: Install documentation incomplete

Submitter:  Jeff <zaphod46>
Submitted:  Tue 21 Aug 2007 03:44:23 PM UTC
   
 
Category:  Documentation Severity:  * 2 - Minor
Item Group:  Non-software error Status:  Ready For Test
Privacy:  Public Assigned to:  gotthardp
Open/Closed:  Closed Release:  * CVS
Reproducibility:  Every Time Fixed Release:  * 3.4.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Fri 12 Nov 2010 08:05:14 AM UTC, comment #12: 

Generated doc is now available at:
/http://www.nongnu.org/certi/certi_doc/index.html

It always has to be improved but it's there
and already usable.

CMake options:

BUILD_DOC
and
BUILD_DOC_xxxx
may be used to build the documentations

Eric NOULARD <erk>
Group administrator
Mon 03 Nov 2008 02:08:29 PM UTC, comment #11: 

Sorry for not answering,
You may have already noticed I have done the update
for PDF doc generation.

I did it using the same png image but
you have to duplicate the
 \image html "rtig.png"
with something like:
 \image latex "rtig.png" "RTIG screenshot" width=12cm

Latex graphicx module used for LaTeX/PDF output should
work just fine with png files, however you may need to have
an up to date LaTeX distribution.
 (like TeX Live http://www.tug.org/texlive/)

Eric NOULARD <erk>
Group administrator
Thu 23 Oct 2008 01:41:42 PM UTC, comment #10: 

It would be great if you do the update. I was not able to convince "it" to use the same image for HTML and PDF. :-(

You can commit it. I have no modiffication underway.

Petr Gotthard <gotthardp>
Group Member
Thu 23 Oct 2008 01:32:20 PM UTC, comment #9: 

Petr,

I'd like to update your modif in order to
be able to include screenshots both in HTML output
and LaTeX/PDF output.

May I commit some update or do currently haveuncommited
modification for the doc?

Eric NOULARD <erk>
Group administrator
Sun 19 Oct 2008 11:21:22 AM UTC, comment #8: 


I agree L1 is the primary doc needed.

I'm Ok with your proposal for

building, installation and configuration/execution

(However I think you meant
 i.e. execution should be also described in L2.)

I'm ok with the renaming too, in fact the certi_ prefix
comes from a previous (now aborted) documentation ideas,
I did keep it, but you are right it is now meaningless.

So go ahead with:

- keep the prefix for the .cnf and .tree files
- remove the prefix for all other files
- rename current "certi_user.dox" to "execute.dox" to better reflect its content


Regarding documentation I won't have time now to work on
that now (but may be L3 here and there while updating some
source code) so go ahead for L1 and L2 we won't overlap now.

If I was about to work on it I'll tell you.
I did re-assign the task to you :-)

On the building part, you may borrow some information
from the:
http://download.savannah.gnu.org/releases/certi/documentation/CERTI-Compilation-HOWTO.odt

it is an Open Office document you may copy paste from.
It contains Windows screenshots.

If you think it would be interesting to add those
screenshots (and may be other for Linux)
in the documentation (you may do it with Doxygen \image
command for both HTML and LATEX output)
may be it would be easier to put all thoses
images files in a to be created certi/doc/images.

Then *.cnf files should be updated with an appropriate
IMAGE_PATH.


Thank you again for your valuable contribution.

Eric NOULARD <erk>
Group administrator
Sat 18 Oct 2008 07:11:14 PM UTC, comment #7: 

Eric,
I will first focus on the L1 documentation only. (I believe that L1 need documentation at most.)

(1)
I think the L1 (install doc) should have at least 3 chapters: building, installation and configuration/execution (i.e. execution should be also described in L1.) Attached is a proposal showing what I mean.

(2)
I'm not sure about the "certi_" prefix for all doc files. It's all CERTI documentation. I would propose to
 -- keep the prefix for the .cnf and .tree files
 -- remove the prefix for all other files
 -- rename current "certi_user.dox" to "execute.dox" to better reflect its content

What do you think?

(file #16696)

Petr Gotthard <gotthardp>
Group Member
Thu 09 Oct 2008 09:19:12 PM UTC, comment #6: 

I agree with your 3 level needs for documentation:

level 1 install (configure+build) CERTI         
level 2 user :
          2.1 run CERTI examples
              env var, rtia, rtig usage etc...
          2.2 develop your federation and run it
              xxx binding API doc (not specific to CERTI)
                  xxx = C++/Python/Matlab/Fortran90 etc...
              building federate with CERTI (CMake, libs etc...)
          2.3 companion API doc coming with CERTI
                  libHLA
level 3 certi API: developer/contributor
              the full CERTI API


The current doxygen config is mostly L3 doc + some L1 in the
main page. Doxygen may be used for L1/L2/L3 but current
config is not setup this way. I'll try to update it
and let you examine if it's appropriate or not.

The pleasant thing with Doxygen usage is that its input
are some text files which are easily handled with CVS
(diff, revision etc...).

Using other format like .doc .odt for L1 or L2 documentation
leads to uneasy handling of versioning which often leads to
outdated documentation.

Latex doc would be nice (and ok for versioning)
for L1 or L2 doc but
may suffer from another drawback which is
 "being separated" from the source.

For example, I think,
the "user" (L2) documentation of the RTIG executable
should be written in the certi/RTIG/main.cc file
which makes it easier to update if the code of the RTIG
is updated.

Doxygen may generate various file format including
tex/pdf, CHM (compress HTML files suitable on Windows),
HTML page sets etc...

So I do not want to convince that we must go for Doxygen
for all L1/L2/L3 doc, but I want to give it a try,
then if you find the result innappropriate then
we can go for separatly handled L1 and L2 doc in either
latex, odt etc... format.

Give me some more days and I'll try to show you
(by example) what I mean.

Eric NOULARD <erk>
Group administrator
Thu 09 Oct 2008 11:38:24 AM UTC, comment #5: 

I compiled the doxymentation and I'm not sure if doxygen can produce documentation for people with different needs.
 (1) There are people that (will) use CERTI as users: install, configure, run simulation, get results, process results.
 (2) There are people that will develop C++ simulations: Write federation ambassador in C++. [The Python users using PyHLA are more or less level (1), because PyHLA will come with own level (2) documentation.]
 (3) There are people that will contribute to CERTI development.

I think we should not confuse people at level X by showing them documentation for level X+1.
The current doxymentation is at level (3). We could hide private class members and the CERTI namespace, but then we get documentation at level (2), losing the level (3). [Well, currently we won't get level (2) anyway because the RTI namespace has no documentation.]
I'm not sure if doxygen can produce a suitable level (1) documentation. The level (1) users shouldn't be scared away by the complexity of the documentation. An acceptable solution would be an "expert section" containg all level (3) namespaces, classes, functions etc. Is this possible?

I write this based on my experiences with level (1) users. If we want CERTI to be widely used, we should support all 3 levels.
I don't say doxygen is a bad solution, I'm just afraid the doxygen is not for every CERTI user.

Petr Gotthard <gotthardp>
Group Member
Wed 08 Oct 2008 09:34:56 PM UTC, comment #4: 

This is true
current documentation is spare and mostly outdated.
The different part have been made by different people
with different needs at different moment in time :-)

The hopefully up to date and unique documentation
should be taken from Doxygen documentation
which is either:

 - embedded in the source code (.h .c .cpp ...)
 - or put in certi/doc/*.dox files.

Using this if you have doxygen installed, you may
cd <builddir>
cmake -DBUILD_API_DOC:BOOL=ON
make doc_forced (this is a make target)
which will produce the HTML documentation inside

<builddir>/doc/reference/html

open
<builddir>/doc/reference/html/index.html
with your favorite browser.

Using this doxygen generated documentation we may produce
a "reference" documentation for CERTI
including install, design & usage, and API reference.

certi/README

should be a "minimal" help for building CERTI no more.

(make install will hopefully install doxygen documentation
 if doxygen was found by CMake).

I did begun the work consisting in collecting sparse
documentation and putting it all together in the doxygen
generated one.
(en var explanation is missing)

Once I'm done with that I'll call for help for an hopefully
concurrent update on different part of the doc
(including the Design & API doc).

I'll update http://www.nongnu.org/certi/ in order
to only refer to certi/README and doxygen generated doc
(I may upload for each
 release inside http://www.nongnu.org/certi/doc)

Concerning the content of
http://download.savannah.gnu.org/releases/certi/documentation

you have the Open Office source (.odt) which is editable
but I'd rather go for doxygen handled doc unless
other hate that mean and prefer to edit "word processing"
document.

If you want to have a look at what can be done with Doxygen
go to: www.doxygen.org

Eric NOULARD <erk>
Group administrator
Wed 08 Oct 2008 09:10:17 PM UTC, comment #3: 

This is not a bug, this is a zombie. ;-) May I also ask you to consolidate the documentation?

- something is in README (including the latest installation instructions)
- something else is under doc/...
- additional pages are in CVS web repository, visible at http://www.nongnu.org/certi/
- and there are more here (including a very useful description of environment variables)
http://www.cert.fr/CERTI/install.en.html
http://www.cert.fr/CERTI/env.en.html
- and there (but without .tex source codes, so it's not possible to contribute)
http://download.savannah.gnu.org/releases/certi/documentation

As the original comment said "Consolidating these will make it simpler to use and maintain."

Petr Gotthard <gotthardp>
Group Member
Mon 27 Aug 2007 10:59:28 PM UTC, comment #2: 

I briefly tried CMake, but I have no experience with it.  I noticed a few CMake files in the CVS version, so I typed "cmake," but it didn't complete the build, so I went back to the old fashioned way.

I'll go back and try to get the exact errors for you.

Jeff <zaphod46>
Tue 21 Aug 2007 04:16:50 PM UTC, comment #1: 

You are right this is missing.
We will consolidate the doc as you said
most probably in two places:

1) a minimal doc in certi/README containing an INSTALL section
2) an more extensive documentation contained
   in doxygen parsable file in order to be able
   to generate either html or printable documentation format
   (pdf may be)


However we should launch a first poll before doing that
because during the Win32 port of CERTI we began to use
CMake (http://www.cmake.org) and we may well replace
autotools with CMake for unix platform too, so we won't
update doc for autotools usage if we drop it :))

What is your opinion on this subject?
Did you try to build CERTI using CMake?
(CVS version of CMake is CMake-ready)




Eric NOULARD <erk>
Group administrator
Tue 21 Aug 2007 03:44:23 PM UTC, original submission:  

The install documentation does not mention that you need to run autogen.sh before the standard "configure && make && make install." It was easy to figure out, but adding a sentence to the install docs will make it even easier.

Also, the install docs are spread across (or duplicated across) at least three different files: README, INSTALL, and doc/install.txt  Consolidating these will make it simpler to use and maintain.

Jeff <zaphod46>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #16696:  doc.zip added by gotthardp (31KiB - application/zip - Proposed change.)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gotthardp (Posted a comment)
  • -email is unavailable- added by erk (Posted a comment)
  • -email is unavailable- added by zaphod46 (Submitted the item)
  •  

    Follow 8 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2010-11-12 erk StatusIn Progress Ready For Test
        Open/ClosedOpen Closed
        Fixed ReleaseNextRelease 3.4.0
    2008-11-03 erk Fixed ReleaseUnknown NextRelease
    2008-10-19 erk Assigned toerk gotthardp
    2008-10-18 gotthardp Attached File- Added doc.zip, #16696
        StatusNone In Progress
    2008-10-08 erk Assigned toNone erk

    Back to the top

    Powered by Savane 3.13-4b48.
    Corresponding source code