Hi Julien,
I'm glad your amazed :).
Regarding you questions:
> Do you want to put a version within the static area so that people can
> read it online ?
Yes. If you can decide where you want it and how you want it to appear.
I will create a different style for online reading though. I'll break the
manual up into smaller chunks, maybe 60 or 70 pages. It's too big as a
single page.
I sent an email to Florent about publishing the book for online reading,
who passed it on to Stefane Fermigier. See the attachment, which contains
my message and the full reply.
> As well, if you wanna check this within the nuxeo repository using
> subversion feel free to ask.
This is probably a good idea too, but I will wait until I have the first
version finished.
> This is really cool for the CPS-3.4 release with this english manual.
As the 3.4 release is getting closer I should try and get the manual
up-to-date for this version. I don't want to publish it and find some key
3.4 features are not mentioned at all.
I would really appreciate it if someone from Nuxeo (you maybe?) can tell
me what needs to be added or changed so the manual is correct for 3.4.
Steve Meaker
Florent Guillaume wrote:
> Begin forwarded message:
>
>> From: "Steve Meaker" <[EMAIL PROTECTED]>
>> Date: 10 September 2005 09:57:49 GMT+02:00
>> To: "Florent Guillaume" <[EMAIL PROTECTED]>
>> Subject: Re: [CPS-users] CPS3 English Manual
>>
>>
>> Hi Florent,
>>
>> I am glad you like the manual so far.
>>
>> I have a couple of items that I want to put to someone on the Nuxeo team
>> before I get to the final publication of the english manual.
>>
>> If this is not your role or job, could you forward this to someone at
>> Nuxeo who could decide?
>>
>> Copyright etc
>> -------------
>>
>> I want to make sure that I have permission from Nuxeo to use the text
>> that
>> I copied from the CPS source directories and from the cps-project.org
>> site.
No problem a priori, all of our public documentation is covered by the
GNU FDL
license.
>> The manual I have written contains many sections and paragraphs that was
>> copied from these sources. Some of this was re-written slightly, but
>> other
>> parts were just copied directly.
>>
>> I was not going to put any restrictions on what other people do with the
>> manual (including Nuxeo). As I am using some of your materials I also
>> need
>> to ensure I don't upset the original authors.
>>
>> What, if any copyright notices or license statements should I include
>> so I
>> don't upset anyone at Nuxeo?
Since our documentation is covered by the GNU FDL, derivative work should
be
covered by the same license, unless you have some reasons to change the
license,
in which case are open to discussion.
Regarding copyright, you should probably put: Copyright <year> Nuxeo SAS.
Copyright <year> Steve Meaker, or something similar.
An important point is that in the original material, there is an "invariant
section" (or there should be one) called "About Nuxeo" which says that we
are
the main authors of CPS and we are such a great company, blah blah. We'd
really
like for this section to stay invariant in your document, and of course
you may
add your own blurb afterwards if you want.
>> Attribution
>> -----------
>>
>> I have included a page in the manual that contains a list of the
>> development team at Nuxeo (I think). I copied this from a page on
>> cps-project.org.
>>
>> I want to make this a thank-you page to the developers of CPS. Can you
>> provide me with the names of any individuals and/or companies that
>> should
>> be included in this section.
There is a list of credits that I put on the home page of
cps-project.org, based
on grepping the source code. I haven't done it at the individual developer
level, though.
>> If there is any other information that Nuxeo would like added, in
>> this or
>> any other part of the manual, please send it to me for incorporation
>> into
>> the published version of the manual.
See above. I will check if the invariant section is indeed included in the
english version of the documentation, if you don't fin it.
>> How to publish the manual on the CPS site?
>> ------------------------------------------
>>
>> I need to decide the final publication format for the manual I am
>> writing.
>>
>> Can you read through this and let me know which approach suits the Nuxeo
>> team the best. I am totally flexible, just let me know which
>> approach, if
>> any works best for your company.
>>
>> I was considering a couple of options for publishing the completed
>> manual.
>>
>> The manual is written in reStructuredText. I use rest2html.py to create
>> the html from the reST. There are about 65 reST files.
>>
>> First, I can upload it in formats suitable for download, HTML, PDF
>> and CHM
>> maybe. This is easy and I'll do this anyway.
>>
>> Second, an online version on the cps-project web site. As I see it there
>> are a few alternatives, of which publishing it as a Book is probably the
>> best option.
>>
>> I tried using the reStructuredText files inside a CPS
>> FlexibleDocument.
>> They didn't work very well at all.
>>
>> I'll have to look into Zopes reStructuredText and see how many changes
>> need to be made. If you have any suggestions about this I'd be happy to
>> hear them.
>>
>> Zipped HTML
>> This works fine for a completed HTML manual, but it isn't available on
>> cps-project.org yet. It is probably not the best option, although it
>> could be made available this way as well when the Zipped HTML product is
>> added to the cps-projet.org site. The 1Mb default file size would need
>> to be changed for this anyway, unless I upload several ZippedHTML
>> files.
>>
>> FlexibleDocument
>> I could upload the sections of the manual as individual
>> FlexibleDocuments. This would be OK, but won't look very good. It is
>> relatively easy and simple.
>>
>> Book
>> Using the the reST files to create a CPS Book has the same problems
>> as the
>> FlexDoc.
>>
>> Uploading the generated HTML pages into Pages of a Book works fine. I
>> could upload the 6 sections of the manual into 6 Book pages, but this
>> isn't going to look much good.
>>
>> It is probably best if I generate individual pages from the reST files
>> and upload each of the 65 or so HTML files into Pages of a Book. I would
>> probably end up with 10 to 15 chapters, and about 100 pages.
>>
>> If I am to do this I will need to change some files so the section,
>> chapter and page structure works correctly, but this shouldn't be too
>> much
>> of a problem for me.
>>
>> The Book would probably look the best, and the search interface in the
>> Book is another advantage.
>>
>> Problems
>> --------
>>
>> Creating the Book using the reST files, or the generated HTML files, has
>> only one problem that I can't resolve by myself. Uploading the images
>> would take too long.
>>
>> Having more than 60 pages, and 10 or more chapters just uploading the
>> html
>> is going to take a while. I can manage this over a period of time.
>>
>> The biggest problem for all approaches above, except the Zipped HTML
>> file, is the images.
>>
>> There are already over 200 images in the manual, and there will be at
>> least another 100 by the time it is finished. I just don't have the time
>> to
>> upload these one at a time.
>>
>> Can you arrange to have the images folder for the completed manual
>> copied
>> to the cps-project.org server so I can link to them from the manual?
>> This
>> can't be done until the manual is finished.
>>
>> If you can I will create a Book and publish it, unless this doesn't suit
>> the Nuxeo team.
>>
>> The name of the images folder (I'm using /images at the moment) will
>> probably need to be changed, so let me know what name to use and any
>> path required, and I'll change the name from images to
>> en_manual_images/xxx/ or whatever is suitable for the CPS site.
>>
>> There are at least 3 ways to use the images
>>
>> I don't have a preference for the images location, I only need to link
>> to them.
>>
>> I have used the CPSLocalFS product to map the images folder on the
>> server disk. Mapping this folder in a hidden section works OK.
>>
>> Using LocalFS (or similar product) and mapping the images folder into
>> the root of the CPS site (or lower) would also work OK. The images
>> aren't visible in CPS, just in the manual. But this is OK, they don't
>> need to be.
>>
>> The images folder doesn't need to be in Zope at all. The images
>> could be
>> served directly by the Apache web server and not be in Zope at all. This
>> also works fine, as long as you use apache.
>>
>> Let me know if you can arrange for the images to be placed on the server
>> and if Nuxeo has any preference for the final published version.
>>
>> Once I have completed the manual Nuxeo can use it as is, or modify it in
>> any way they want to.
>>
>> Of course, if you have any other suggestions for publication I will
>> consider these too.
>>
>> I will continue with what I have done so far. I will add images to
>> all of
>> the text that I have, and re-write the text as I go. I expect Version
>> 1 of
>> the manual to be finished within a month.
The best way would probably to provide a custom document type to manage
complete
books as HTML (either one big file or several small ones) + supporting
files,
uploaded as a ZIP file. We need it for other documentation. I'll see what
we can
do with this idea.
Regards, and thanks for you good work.
S.
--
Stéfane Fermigier, Tel: +33 (0)6 63 04 12 77 (mobile).
Nuxeo Collaborative Portal Server: http://www.nuxeo.com/cps
Gestion de contenu web / portail collaboratif / groupware / open source!
_______________________________________________
cps-users mailing list
[email protected]
http://lists.nuxeo.com/mailman/listinfo/cps-users
