Re: [Rodin-handbook] Modifying the handbook/wiki

[Michael J. <mi...@ja...>]

Hi Nicolas,

Good questions.  We will definitely keep the Wiki around, as it contains
much more than what will go into the handbook: Announcements,
Plugin-Documentation, etc.

The content that gets migrated into the handbook will be removed from
the wiki (which is better then letting those pages become out of date). 
But we won't do this until the next iteration review.

> In this case, wouldn't it be good to replace the whole wiki contents
> of migrated pages by a link to the up-to-date html handbook
> (sub)section ? 

Yes, we definitely need a link from the wiki to the handbook, and such a
link already exists.  Once the migrated pages are removed, we will make
it more prominent.  In fact, I suggest to provide links to the top level
chapters of the handbook in the navigation (e.g. a link to FAQ,
Reference and Tutorial).

> Alternatively, could we imagine an automatic synchronization
> (regeneration) of the LaTeX sources from the wiki ? 

We looked into this option before we started, but decided against it. 
For one, it would add little value (we generate an HTML version, why do
we need a redundant Wiki version?).  And second, going from Wiki to
Latex will result in a lower quality PDF version, for a number of reasons.

Now we have exactly one source (Latex) and three generated artifacts
(HTML, PDF, Eclipse Help).  This approach seems to scale well and
results in decent documentation in all three formats.

What do you think?

Best,

- Michael

On 09/22/2011 10:41 AM, Nicolas Beauger wrote:
> Hi Michael,
>
> Thank you, that's what I was thinking. It's a bit less practical than
> editing the wiki but I can live with that.
> But thus, will the wiki pages be updated after a LaTeX build ?
> If not, it means that we are definitely dropping the wiki, letting
> pages become out of date.
> In this case, wouldn't it be good to replace the whole wiki contents
> of migrated pages by a link to the up-to-date html handbook
> (sub)section ?
> Alternatively, could we imagine an automatic synchronization
> (regeneration) of the LaTeX sources from the wiki ?
>
> Cheers,
> Nicolas
>
> Le 21/09/2011 20:37, Michael Jastram a écrit :
>> Hi Nicolas,
>>
>> I'll CC the handbook mailing list, as this may be useful information for
>> others as well.
>>
>>> I have a question about the handbook. The wiki pages integrated in the
>>> handbook have a "Do not edit!" panel on the top: does it mean they
>>> cannot be modified anyhow ? or is it possible to modify them through
>>> subversion ?
>> It simply means that we converted the content to Latex and copied it to
>> subversion.  We added this panel to prevent content that we migrated
>> from being modified (thereby missing potentially important changes).
>> The plan is to remove content that is marked that way after a short
>> transition period.
>>
>> If there is content that you need to edit, we'd be grateful if you could
>> do this in subversion - it's essentially plain latex.
>>
>> Best,
>>
>> - Michael
>>
>>
>> On 09/21/2011 06:29 PM, Nicolas Beauger wrote:
>>> Hi Michael, Lukas,
>>>
>>> I have a question about the handbook. The wiki pages integrated in the
>>> handbook have a "Do not edit!" panel on the top: does it mean they
>>> cannot be modified anyhow ? or is it possible to modify them through
>>> subversion ?
>>>
>>> Cheers,
>>> Nicolas
>>>
>>
>


-- 
Michael Jastram (http://www.jastram.de, +49 (162) 274 83 94)
Wissenschaftler, Heinrich Heine Universität Düsseldorf (http://www.stups.uni-duesseldorf.de)
1. Vorsitzender, rheinjug e.V. (http://www.rheinjug.de)