for documenting technical aspects of my code I'd like to use a wiki that is simply a set of files in wiki syntax on my disk (but managed in the revision control system, together with the code).

WikiText already gets me quite close to this. I have several textile files and they are all nicely displayed in preview mode. Thanks a lot to the people who made this possible.

The main thing I'd still need is that clicking a (relative) link to another file actually opens that file in an editor tab instead of showing the source in a browser tab. That would be just like the behavior of F3 in Java source. (It would also be nice if one could follow links in WikiText's source view, but that's not so urgent.)

Is this already possible and I just didn't find out how?

If it's not yet possible: Could it be added? Or does it contradict some underlying WikiText philosopy?

On 10/02/10 10:51 AM, Heribert Schütz wrote:
> Hi,
>
> for documenting technical aspects of my code I'd like to use a wiki that
> is simply a set of files in wiki syntax on my disk (but managed in the
> revision control system, together with the code).

Sounds good!

> WikiText already gets me quite close to this. I have several textile
> files and they are all nicely displayed in preview mode. Thanks a lot to
> the people who made this possible.
>
> The main thing I'd still need is that clicking a (relative) link to
> another file actually opens that file in an editor tab instead of
> showing the source in a browser tab. That would be just like the
> behavior of F3 in Java source. (It would also be nice if one could
> follow links in WikiText's source view, but that's not so urgent.)

Textile links are designed to link to a filename. For example "The Mylyn Homepage":http://www.eclipse.org/mylyn
It'll work fine for you if you want the links to resolve once you've generated HTML from the Textile source. For
example, given two pages:

one.textile
two.textile

You should be able to link from one to two as follows: "two":two.html

> Is this already possible and I just didn't find out how?
>
> If it's not yet possible: Could it be added? Or does it contradict some
> underlying WikiText philosopy?

Perhaps Mylyn WikiText should be smart enough to support your workflow, in other words if you click on the link in the
source view it should open the editor for the textile file instead of the HTML file.

If this is what you'd like to see please file a bug for this under Tools/Mylyn/WikiText

thanks for your answers. I'm not sure whether my previous post was completely clear. So I elaborate a bit more.

> It'll work fine for you if you want the links to resolve once you've generated
> HTML from the Textile source. For example, given two pages:
>
> one.textile
> two.textile
>
> You should be able to link from one to two as follows: "two":two.html

Yes, that's what I already understood. And that might be appropriate in a situation where the roles of authors and readers are clearly separated. The readers who follow the links will never see the original wiki files but only the generated html files and thus for them an html-to-html link is appropriate.

In my use case (technical code documentation) the situation is different: My colleagues and me are at the same time authors and readers of these files. When I follow a link, I want to be able to edit the file without searching for the wiki source of some html file. So I'd prefer textile-to-textile (actually wiki-source-to-wiki-source) links.

In addition I'd prefer to avoid the hassles of generating and managing html files:
- automating the translation from wiki to html (e.g., whenever I save a wiki file)
- configuring revision control to ignore these redundant html files, and
- ensuring that html files are also generated whenever I get a new or updated
wiki file from revision control.

Of course WikiText could come with all this automation and it could hide the generated html files from me in the same way as I need not deal with class files when I write Java code. But that would be quite some effort.

I thought a much easier solution would be to support links like "two":two.textile within one.textile. Following this link in preview mode already does open two.textile (i.e., the wiki source) as I like, but unfortunately in a browser tab where I cannot edit it. I hoped that links to wiki files could simply be intercepted and opened in an editor tab instead (at least if the resource is writable).

> Perhaps Mylyn WikiText should be smart enough to support your workflow, in other
> words if you click on the link in the source view it should open the editor for the
> textile file instead of the HTML file.

I think a link like "two":two.textile in the wiki file would be better than "two":two.html, even for use cases where the wiki source is not delivered to the readers. This is because a link to two.html only works with translation to html whereas a link to two.textile can be adapted to any translation target, e.g., docbook.

But these were just some general thoughts. They are not needed for my use case but show that my suggestion above (to support source-to-source links) is not just a hack.

On 14/02/10 4:12 PM, Heribert Schütz wrote:
> Hi David,
>
> thanks for your answers. I'm not sure whether my previous post was
> completely clear. So I elaborate a bit more.
>
>> It'll work fine for you if you want the links to resolve once you've
>> generated
>> HTML from the Textile source. For example, given two pages:
>>
>> one.textile
>> two.textile
>>
>> You should be able to link from one to two as follows: "two":two.html
>
> Yes, that's what I already understood. And that might be appropriate in
> a situation where the roles of authors and readers are clearly
> separated. The readers who follow the links will never see the original
> wiki files but only the generated html files and thus for them an
> html-to-html link is appropriate.
>
> In my use case (technical code documentation) the situation is
> different: My colleagues and me are at the same time authors and readers
> of these files. When I follow a link, I want to be able to edit the file
> without searching for the wiki source of some html file. So I'd prefer
> textile-to-textile (actually wiki-source-to-wiki-source) links.

That makes sense to me.

Such links should work from the source view as well (with the usual keyboard modifier such as CTRL+Click or
Command+Click on a mac).

Please file a bug if you think an enhancement is needed here.

> In addition I'd prefer to avoid the hassles of generating and managing
> html files:
> - automating the translation from wiki to html (e.g., whenever I save a
> wiki file)
> - configuring revision control to ignore these redundant html files, and
> - ensuring that html files are also generated whenever I get a new or
> updated
> wiki file from revision control.

Agreed, for your use case it makes sense to not have to generate anything when using the files locally, though it would
be nice if these links did not preclude that option. For example, perhaps links such as "one":one.textile should
automatically be modified to point to the corresponding HTML file when generating HTML (as you describe below).

> ...

> I thought a much easier solution would be to support links like
> "two":two.textile within one.textile. Following this link in preview
> mode already does open two.textile (i.e., the wiki source) as I like,
> but unfortunately in a browser tab where I cannot edit it. I hoped that
> links to wiki files could simply be intercepted and opened in an editor
> tab instead (at least if the resource is writable).

Please file a bug describing this issue

>
>> Perhaps Mylyn WikiText should be smart enough to support your
>> workflow, in other
>> words if you click on the link in the source view it should open the
>> editor for the
>> textile file instead of the HTML file.
>
> I think a link like "two":two.textile in the wiki file would be better
> than "two":two.html, even for use cases where the wiki source is not
> delivered to the readers. This is because a link to two.html only works
> with translation to html whereas a link to two.textile can be adapted to
> any translation target, e.g., docbook.

>
> But these were just some general thoughts. They are not needed for my
> use case but show that my suggestion above (to support source-to-source
> links) is not just a hack.
>
> Regards,
> Heribert.
>

thanks for your answers. I'm not sure whether my previous post was completely clear. So I elaborate a bit more.

> It'll work fine for you if you want the links to resolve once you've generated
> HTML from the Textile source. For example, given two pages:
>
> one.textile
> two.textile
>
> You should be able to link from one to two as follows: "two":two.html

Yes, that's what I already understood. And that might be appropriate in a situation where the roles of authors and readers are clearly separated. The readers who follow the links will never see the original wiki files but only the generated html files and thus for them an html-to-html link is appropriate.

In my use case (technical code documentation) the situation is different: My colleagues and me are at the same time authors and readers of these files. When I follow a link, I want to be able to edit the file without searching for the wiki source of some html file. So I'd prefer textile-to-textile (actually wiki-source-to-wiki-source) links.

In addition I'd prefer to avoid the hassles of generating and managing html files:
- automating the translation from wiki to html (e.g., whenever I save a wiki file)
- configuring revision control to ignore these redundant html files, and
- ensuring that html files are also generated whenever I get a new or updated
wiki file from revision control.

Of course WikiText could come with all this automation and it could hide the generated html files from me in the same way as I need not deal with class files when I write Java code. But that would be quite some effort.

I thought a much easier solution would be to support links like "two":two.textile within one.textile. Following this link in preview mode already does open two.textile (i.e., the wiki source) as I like, but unfortunately in a browser tab where I cannot edit it. I hoped that links to wiki files could simply be intercepted and opened in an editor tab instead (at least if the resource is writable).

> Perhaps Mylyn WikiText should be smart enough to support your workflow, in other
> words if you click on the link in the source view it should open the editor for the
> textile file instead of the HTML file.

I think a link like "two":two.textile in the wiki file would be better than "two":two.html, even for use cases where the wiki source is not delivered to the readers. This is because a link to two.html only works with translation to html whereas a link to two.textile can be adapted to any translation target, e.g., docbook.

But these were just some general thoughts. They are not needed for my use case but show that my suggestion above (to support source-to-source links) is not just a hack.

On 14/02/10 4:12 PM, Heribert Schütz wrote:
> Hi David,
>
> thanks for your answers. I'm not sure whether my previous post was
> completely clear. So I elaborate a bit more.
>
>> It'll work fine for you if you want the links to resolve once you've
>> generated
>> HTML from the Textile source. For example, given two pages:
>>
>> one.textile
>> two.textile
>>
>> You should be able to link from one to two as follows: "two":two.html
>
> Yes, that's what I already understood. And that might be appropriate in
> a situation where the roles of authors and readers are clearly
> separated. The readers who follow the links will never see the original
> wiki files but only the generated html files and thus for them an
> html-to-html link is appropriate.
>
> In my use case (technical code documentation) the situation is
> different: My colleagues and me are at the same time authors and readers
> of these files. When I follow a link, I want to be able to edit the file
> without searching for the wiki source of some html file. So I'd prefer
> textile-to-textile (actually wiki-source-to-wiki-source) links.

That makes sense to me.

Such links should work from the source view as well (with the usual keyboard modifier such as CTRL+Click or
Command+Click on a mac).

Please file a bug if you think an enhancement is needed here.

> In addition I'd prefer to avoid the hassles of generating and managing
> html files:
> - automating the translation from wiki to html (e.g., whenever I save a
> wiki file)
> - configuring revision control to ignore these redundant html files, and
> - ensuring that html files are also generated whenever I get a new or
> updated
> wiki file from revision control.

Agreed, for your use case it makes sense to not have to generate anything when using the files locally, though it would
be nice if these links did not preclude that option. For example, perhaps links such as "one":one.textile should
automatically be modified to point to the corresponding HTML file when generating HTML (as you describe below).

> ...

> I thought a much easier solution would be to support links like
> "two":two.textile within one.textile. Following this link in preview
> mode already does open two.textile (i.e., the wiki source) as I like,
> but unfortunately in a browser tab where I cannot edit it. I hoped that
> links to wiki files could simply be intercepted and opened in an editor
> tab instead (at least if the resource is writable).

Please file a bug describing this issue

>
>> Perhaps Mylyn WikiText should be smart enough to support your
>> workflow, in other
>> words if you click on the link in the source view it should open the
>> editor for the
>> textile file instead of the HTML file.
>
> I think a link like "two":two.textile in the wiki file would be better
> than "two":two.html, even for use cases where the wiki source is not
> delivered to the readers. This is because a link to two.html only works
> with translation to html whereas a link to two.textile can be adapted to
> any translation target, e.g., docbook.

>
> But these were just some general thoughts. They are not needed for my
> use case but show that my suggestion above (to support source-to-source
> links) is not just a hack.
>
> Regards,
> Heribert.
>