Home » Eclipse Projects » Mylyn » Mylyn Wiki Help
| | |
| Re: Mylyn Wiki Help [message #489433 is a reply to message #489430] |
Fri, 02 October 2009 23:23   |
 Miles Parker
Messages: 1341
Registered: July 2009 |
Senior Member |
|
|
Following up on my own post, an even simpler approach would be to
specify one "official" UserGuide/Contents page. Then the ant script
could very easily parse that and generate any document format from it.
Plus it would be a nice resource for Wiki readers.
On 2009-10-02 16:16:01 -0700, Miles Parker <milesparker@gmail.com> said:
>
> Thanks for all the links -- extremely helpful.
>
> On 2009-10-02 15:27:16 -0700, David Green <dgreen99@gmail.com> said:
>> You'll find that Eclipse help has some really neat facilities with
>> anchors and links: you can compose almost any structure in the Eclipse
>> help table of contents with multiple documents. This means that you
>> should be able to break your user guide into multiple documents with
>> some tweaking of help toc.xml files.
>
> Yeah, makes sense. It would be nice to not have to maintain the toc
> though. The really great thing about the current Mylyn approch is that
> you don't have to do *anything* whereas if you are using document
> hierarchy you've got to maintain that linkage manually. Which means
> that if a user adds a new page, that's not going to show up. But it
> seems that it wouldn't be too hard to setup a script to say grab every
> document under wiki.eclipse.org/myproject/UserGuide, convert it, and
> then generate a toc for it. You could avoid all of the doc book
> assembly by simply organizing the documentation hierachrchiaclly, e.g.
>
> UserGuide/Overview/..
> UserGuide/Getting_Started/..
>
> With the assumption that everything at a given level is within same
> document (sub)section. Then you would simply have say one Contents Page
> at each level that would define the ordering within that section. but
> it seems that it would at least handle the cannonical case. I'm
> thinking that anything that can be done to give Wiki users full control
> over the end state of the documentation is to the good. Perhaps someone
> has already thought of all that..
>
>
>>
>> As far as I know XText is using WikiText to produce their documentation
>> from wiki format, using DocBook as an intermediary form.
>
> I was thinking that must be the case.
>
> BTW, have you thought about any possiblity of providing editing for
> online content from WikiText? I didn't see anything on this anywhere
> and I don't know if it is even a reasonable thing to do WRT to the Wiki
> side of things.
|
|
| | |
| Re: Mylyn Wiki Help [message #502868 is a reply to message #491852] |
Thu, 10 December 2009 05:38 |
Miles Parker
Messages: 1341
Registered: July 2009 |
Senior Member |
|
|
| Peter Friese wrote on Fri, 16 October 2009 04:18 |
That's right, the Xtext team uses WikiText do write their documentation and we're *very* satisfied with it. If you're intersted, here is the link to our build script: ...
Although it would be great to use the Eclipse wiki to crowdsource the documentaiton, we decided against that. Mainly due to the somehow cumbersome syntax of MediWiki. Or, to express it in a more positive way: we like Textile syntax 
|
Cool, thanks a lot for the links Peter, very helpful. Just a quick question for this thread. So you're actually doing something like:
textile -> wiki
textile -> Eclipse docs
as opposed to
wiki -> Eclipse Docs
??
And as a genral addendum, I've got doc sections seperated now, but I'm thinking of re-integrating them as even on Wiki it's surprisingly difficult to navigate between sections and I'm finding I'm having to spend a fair amount of time maintaining the references between TOC, overview and sections. Sure seems like it might be sipler to have one big page for each of the major components as Mylyn and XText seem to be doing.
|
|
|
| Re: Mylyn Wiki Help [message #502870 is a reply to message #502868] |
Thu, 10 December 2009 06:50 |
Peter Friese
Messages: 30
Registered: July 2009 |
Member |
|
|
| Miles Parker wrote on Thu, 10 December 2009 00:38 | | Peter Friese wrote on Fri, 16 October 2009 04:18 |
That's right, the Xtext team uses WikiText do write their documentation and we're *very* satisfied with it. If you're intersted, here is the link to our build script: ...
Although it would be great to use the Eclipse wiki to crowdsource the documentaiton, we decided against that. Mainly due to the somehow cumbersome syntax of MediWiki. Or, to express it in a more positive way: we like Textile syntax
|
Cool, thanks a lot for the links Peter, very helpful. Just a quick question for this thread. So you're actually doing something like:
textile -> wiki
textile -> Eclipse docs
as opposed to
wiki -> Eclipse Docs
??
|
Not quite. We do
textile (files stored on workspace, resp. CVS) -> docbook -> PDF
textile (files stored on workspace, resp. CVS) -> docbook -> Eclipse Help
textile (files stored on workspace, resp. CVS) -> docbook -> HTML
We were considering writing our documentation on the Eclipse wiki and the transform (wiki -> docbook -> [PDF|HTML|Eclipse Help], but decided against this approach for the following reasons:
- Textile syntax is much more concise than any other Wiki markup, including the dialect being used on the Eclipse wiki
- We needed to introduce special syntax for linking to files in Eclipse CVS, this was easier with WikiText / Textile.
| Quote: |
And as a genral addendum, I've got doc sections seperated now, but I'm thinking of re-integrating them as even on Wiki it's surprisingly difficult to navigate between sections and I'm finding I'm having to spend a fair amount of time maintaining the references between TOC, overview and sections. Sure seems like it might be sipler to have one big page for each of the major components as Mylyn and Xtext seem to be doing.
|
We use a text file to configure the structure of the entire document. This works very well.
|
|
| | |
| Re: Mylyn Wiki Help [message #599381 is a reply to message #489430] |
Fri, 02 October 2009 23:23 |
Miles Parker
Messages: 1341
Registered: July 2009 |
Senior Member |
|
|
Following up on my own post, an even simpler approach would be to
specify one "official" UserGuide/Contents page. Then the ant script
could very easily parse that and generate any document format from it.
Plus it would be a nice resource for Wiki readers.
On 2009-10-02 16:16:01 -0700, Miles Parker <milesparker@gmail.com> said:
>
> Thanks for all the links -- extremely helpful.
>
> On 2009-10-02 15:27:16 -0700, David Green <dgreen99@gmail.com> said:
>> You'll find that Eclipse help has some really neat facilities with
>> anchors and links: you can compose almost any structure in the Eclipse
>> help table of contents with multiple documents. This means that you
>> should be able to break your user guide into multiple documents with
>> some tweaking of help toc.xml files.
>
> Yeah, makes sense. It would be nice to not have to maintain the toc
> though. The really great thing about the current Mylyn approch is that
> you don't have to do *anything* whereas if you are using document
> hierarchy you've got to maintain that linkage manually. Which means
> that if a user adds a new page, that's not going to show up. But it
> seems that it wouldn't be too hard to setup a script to say grab every
> document under wiki.eclipse.org/myproject/UserGuide, convert it, and
> then generate a toc for it. You could avoid all of the doc book
> assembly by simply organizing the documentation hierachrchiaclly, e.g.
>
> UserGuide/Overview/..
> UserGuide/Getting_Started/..
>
> With the assumption that everything at a given level is within same
> document (sub)section. Then you would simply have say one Contents Page
> at each level that would define the ordering within that section. but
> it seems that it would at least handle the cannonical case. I'm
> thinking that anything that can be done to give Wiki users full control
> over the end state of the documentation is to the good. Perhaps someone
> has already thought of all that..
>
>
>>
>> As far as I know XText is using WikiText to produce their documentation
>> from wiki format, using DocBook as an intermediary form.
>
> I was thinking that must be the case.
>
> BTW, have you thought about any possiblity of providing editing for
> online content from WikiText? I didn't see anything on this anywhere
> and I don't know if it is even a reasonable thing to do WRT to the Wiki
> side of things.
|
|
| | |
| Re: Mylyn Wiki Help [message #600163 is a reply to message #599718] |
Thu, 10 December 2009 05:38 |
Miles Parker
Messages: 1341
Registered: July 2009 |
Senior Member |
|
|
Peter Friese wrote on Fri, 16 October 2009 04:18
> That's right, the Xtext team uses WikiText do write their documentation and we're *very* satisfied with it. If you're intersted, here is the link to our build script: ...
> Although it would be great to use the Eclipse wiki to crowdsource the documentaiton, we decided against that. Mainly due to the somehow cumbersome syntax of MediWiki. Or, to express it in a more positive way: we like Textile syntax :)
Cool, thanks a lot for the links Peter, very helpful. Just a quick question for this thread. So you're actually doing something like:
textile -> wiki
textile -> Eclipse docs
as opposed to
wiki -> Eclipse Docs
??
And as a genral addendum, I've got doc sections seperated now, but I'm thinking of re-integrating them as even on Wiki it's surprisingly difficult to navigate between sections and I'm finding I'm having to spend a fair amount of time maintaining the references between TOC, overview and sections. Sure seems like it might be sipler to have one big page for each of the major components as Mylyn and XText seem to be doing.
|
|
|
| Re: Mylyn Wiki Help [message #600168 is a reply to message #600163] |
Thu, 10 December 2009 06:50 |
Peter Friese
Messages: 30
Registered: July 2009 |
Member |
|
|
Miles Parker wrote on Thu, 10 December 2009 00:38
> Peter Friese wrote on Fri, 16 October 2009 04:18
> > That's right, the Xtext team uses WikiText do write their documentation and we're *very* satisfied with it. If you're intersted, here is the link to our build script: ...
> > Although it would be great to use the Eclipse wiki to crowdsource the documentaiton, we decided against that. Mainly due to the somehow cumbersome syntax of MediWiki. Or, to express it in a more positive way: we like Textile syntax :)
>
>
> Cool, thanks a lot for the links Peter, very helpful. Just a quick question for this thread. So you're actually doing something like:
>
> textile -> wiki
> textile -> Eclipse docs
>
> as opposed to
>
> wiki -> Eclipse Docs
>
> ??
Not quite. We do
textile (files stored on workspace, resp. CVS) -> docbook -> PDF
textile (files stored on workspace, resp. CVS) -> docbook -> Eclipse Help
textile (files stored on workspace, resp. CVS) -> docbook -> HTML
We were considering writing our documentation on the Eclipse wiki and the transform (wiki -> docbook -> [PDF|HTML|Eclipse Help], but decided against this approach for the following reasons:
Textile syntax is much more concise than any other Wiki markup, including the dialect being used on the Eclipse wiki
We needed to introduce special syntax for linking to files in Eclipse CVS, this was easier with WikiText / Textile.
Quote:
> And as a genral addendum, I've got doc sections seperated now, but I'm thinking of re-integrating them as even on Wiki it's surprisingly difficult to navigate between sections and I'm finding I'm having to spend a fair amount of time maintaining the references between TOC, overview and sections. Sure seems like it might be sipler to have one big page for each of the major components as Mylyn and Xtext seem to be doing.
We use a text file to configure the structure of the entire document. This works very well.
|
|
|
Goto Forum:
Current Time: Tue Apr 16 13:25:40 GMT 2024
Powered by FUDForum. Page generated in 1.03664 seconds |
] 
Search
Help
Register
Login
Home
