Eclipse Community Forums: Mylyn » [wikitext] Embedding links, etc..

Help

Home

Home » Eclipse Projects » Mylyn » [wikitext] Embedding links, etc..

Show: Today's Messages :: Show Polls :: Message Navigator

[wikitext] Embedding links, etc.. [message #527081]

Tue, 13 April 2010 23:24

Miles Parker

Messages: 1341
Registered: July 2009

Senior Member

As others have said, this is a great contribution.

As background, I'm auto-creating docs using a setup stolen from the xtext docs builder -- my setup is basically the same except that I'm suing mediawiki instead. (You can see the generated docs here.. http://eclipse.org/amp/documentation/) So that means that I actually have docbooks XSL in the mix and so this is a little OT, but I'm hoping that there are other wikitext / docbooks users here who might have ideas.

First, I would like to be able to generate all of my docs automatically, but there is one issue there. I don't think there is a way to get TOC links generated, is there? I've got some links such as API docs that aren't coming from wikitext. (I thought of having a Master toc and then linking the Wiki generated docs in to that, but can't get that working the way I'd like.) And ideas about how I might get these links auto-genrated so that I don't have to re-edit my toc each time I do an update?

Second, I wonder if anyone has built a docbook2html or wiki2html target that separates the html into separate pages for say each h1 / =blah= level heading? My docs are getting large and I don't want users to have to download dozens of images and 30 pages of text everytime they go to the docs page.

thanks for any help or hints,

Miles

Report message to a moderator

Re: [wikitext] Embedding links, etc.. [message #527082 is a reply to message #527081]

Tue, 13 April 2010 23:26

Miles Parker

Messages: 1341
Registered: July 2009

Senior Member

Yikes, I should clarify that I'm not suing mediawiki, that would be bad form indeed. I'm *using* mediawiki. Smile

Report message to a moderator

Re: [wikitext] Embedding links, etc.. [message #527086 is a reply to message #527081]

Wed, 14 April 2010 00:30

Miles Parker

Messages: 1341
Registered: July 2009

Senior Member

An update on the second. This seems like it should be pretty easy to do with docbook chunking and in fact I've been able to get it working -- the only issue is that I can't figure out how to get the toc to generate. The index.html that is generated doesn't include one.

Here's what I did for those who are interested..

1. Copied the chunk.xsl, chunk-common.xsl and chunk-code.xsl into my styles dir.
2. Modified the html.xsl like so:

<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:exsl="http://exslt.org/common"
		version="1.0"
                exclude-result-prefixes="exsl">

    <xsl:import href="chunk.xsl" />
	<xsl:output method="html" indent="yes" encoding="ISO-8859-1" omit-xml-declaration="yes" />

    <xsl:param name="html.stylesheet">book.css</xsl:param>


    <xsl:param name="chunk.first.sections" select="1" />
    <xsl:param name="chunk.section.depth" select="1" />
    <xsl:param name="use.id.as.filename" select="1" />
    <xsl:param name="suppress.navigation" select="0" />
    <xsl:param name="chapter.autolabel" select="1" />
    <xsl:param name="table.borders.with.css" select="1"></xsl:param>
    <xsl:param name="table.cell.border.color" select="'#000000'"></xsl:param>
    <xsl:param name="table.cell.border.thickness" select="'2'"></xsl:param>
    <xsl:param name="html.cellspacing" select="'0'"></xsl:param>
    <xsl:param name="html.cellpadding" select="'10'"></xsl:param>

    <xsl:param name="html.cleanup" select="1"></xsl:param>

    <xsl:param name="generate.toc">
		appendix  nop
		article/appendix  nop
		article   nop
		book      toc,title,figure,table,example,equation
		chapter   nop
		part      nop
		preface   nop
		qandadiv  nop
		qandaset  nop
		reference nop
		sect1     nop
		sect2     nop
		sect3     nop
		sect4     nop
		sect5     nop
		section   nop
		set       nop
    </xsl:param>

</xsl:stylesheet>

Report message to a moderator

Re: [wikitext] Embedding links, etc.. [message #529244 is a reply to message #527081]

Fri, 23 April 2010 14:12

David Green

Messages: 136
Registered: July 2009

Senior Member

Miles,

Some answers below:

On 10-04-13 4:24 PM, Miles Parker wrote:
> As others have said, this is a great contribution.
>
> As background, I'm auto-creating docs using a setup stolen from the
> xtext docs builder -- my setup is basically the same except that I'm
> suing mediawiki instead. (You can see the generated docs here..
> http://eclipse.org/amp/documentation/) So that means that I actually
> have docbooks XSL in the mix and so this is a little OT, but I'm hoping
> that there are other wikitext / docbooks users here who might have ideas.

We have quite a few users integrating with DocBook XSL. WikiText enables integration with existing toolchains so that
it's easy to use existing publishing infrastructure. Some people also like integrating with DocBook XSL for the extra
control it gives them over the output.

There have been significant advancements on MediaWiki integration, I recommend that you take a look at
http://wiki.eclipse.org/DocumentationGuidelines/CrowdSourcin gExample
You may find that following this example greatly simplifies your process.

> First, I would like to be able to generate all of my docs automatically,
> but there is one issue there. I don't think there is a way to get TOC
> links generated, is there? I've got some links such as API docs that
> aren't coming from wikitext. (I thought of having a Master toc and then
> linking the Wiki generated docs in to that, but can't get that working
> the way I'd like.) And ideas about how I might get these links
> auto-genrated so that I don't have to re-edit my toc each time I do an
> update?

I recommend that you take a look at the Mylyn help bundle
http://wiki.eclipse.org/DocumentationGuidelines/CrowdSourcin gExample#Mylyn
It shows how to maintain a master TOC with anchors and links, integrating generated TOC.

>
> Second, I wonder if anyone has built a docbook2html or wiki2html target
> that separates the html into separate pages for say each h1 / =blah=
> level heading? My docs are getting large and I don't want users to have
> to download dozens of images and 30 pages of text everytime they go to
> the docs page.

This is easy to do either with WikiText directly or by using DocBook XSL chunking.

Regards,

David

> thanks for any help or hints,
>
> Miles

Report message to a moderator

Re: [wikitext] Embedding links, etc.. [message #529299 is a reply to message #529244]

Fri, 23 April 2010 17:58

Miles Parker

Messages: 1341
Registered: July 2009

Senior Member

Thanks David, thanks for the links, I had taken a close look at a bunch of those docs, but I see you've added a bunch of new stuff there now.

please see below..

David Green wrote on Fri, 23 April 2010 10:12

Miles,

I recommend that you take a look at the Mylyn help bundle
http://wiki.eclipse.org/DocumentationGuidelines/CrowdSourcin gExample#Mylyn
It shows how to maintain a master TOC with anchors and links, integrating generated TOC.

Thanks for the link -- hopefully that will get me to fully automated integration including external inks.

As a bit more background, after much consideration, I'm taking the XText approach, which takes care of reintegrating everything in order nicely. I've decided that the trade off between crowdsourcing and being able to maintain the docs in SVN and easily edit them in WikiText is heavily stacked toward the latter -- I've got a ton of documentation to write and I can't imagine trying to do it off of the web. But I'm using mediawiki as my markup language so down the line I'll be able to convert it back to the wiki. I'd love to see some sort of auto update process, integrated with a compare feature (e.g. a VCS client for MediaWiki!) but that seems like it would be a pretty thorny project...I'm not even sure that the wiki server side has an API that could be used for that -- you might end up having to spoof a regular user which is fraught with difficulties.

Anyway the XText approach is really cool, because you can fragment the document in any way you want. You could use this to allow other developers to override and add to sections product specific documentation for example at build time. Then of course it generates the TOC, etc.. based on the final assembled documentation. For those who haven't taken a look at their customBuild.xml you should as it is is really nice example (and there are plenty of others i the Eclipse world) of ant done well. The project structure looks a bit intimidating at first, but its actually super easy to modify for your own uses. I just:

1. Grabbed the existing structure into my project.
2. Changed all of the XText specific stuff for my project.
3. Changed the targets from textile to mediawiki.
3. Replaced the contents of doc with my own mediakwiki files and added the myproject-index.txt contents file.

For those interested, my project is at cvsroot/modeling org.eclipse.amp/org.eclipse.amp/doc/org.eclipse.amp.doc

Quote:

>
> Second, I wonder if anyone has built a docbook2html or wiki2html target
> that separates the html into separate pages for say each h1 / =blah=
> level heading? My docs are getting large and I don't want users to have
> to download dozens of images and 30 pages of text everytime they go to
> the docs page.

This is easy to do either with WikiText directly or by using DocBook XSL chunking.

I think I'd like to do it in XSL as I want to be able to maintain it at the presentation level -- for example, it would be nice to be able to fragment at different section levels as the content per section gets bigger. And there might be different uses for which different level of segmentation make more sense..

So, I have to ask, I didn't actually find it "easy" Smile

, in fact I could get it to work. Do you (or anyone out there) know of any projects using XSL chunking that I could take a look at? Xtext AFAICT isn't doing any chunking.

cheers,

Miles

Report message to a moderator

Re: [wikitext] Embedding links, etc.. [message #529982 is a reply to message #529299]

Tue, 27 April 2010 21:46

Miles Parker

Messages: 1341
Registered: July 2009

Senior Member

Miles Parker wrote on Fri, 23 April 2010 13:58

So, I have to ask, I didn't actually find it "easy" Smile

, in fact I could get it to work. Do you (or anyone out there) know of any projects using XSL chunking that I could take a look at?

I figured this out. I think I must have had something messed up in the configuration as the basic steps I was taking were correct. For others, you just:

1. Copy chunk.xsl, chunk-common.xsl and chunk-code.xsl into your styles dir
2. In html.xss, change docbook.xsl to chunk.xsl
3. Customize the chunking according to the docbook chunking docs.

One change you'll want to make to match with the xtext structure is to get rid of the base.dir attribute. See the preceeding message for a reference to the amp project implementation.

Report message to a moderator

Re: [wikitext] Embedding links, etc.. [message #601207 is a reply to message #529244]

Fri, 23 April 2010 17:58

Miles Parker

Messages: 1341
Registered: July 2009

Senior Member

Thanks David, thanks for the links, I had taken a close look at a bunch of those docs, but I see you've added a bunch of new stuff there now.

please see below..

David Green wrote on Fri, 23 April 2010 10:12
> Miles,
>
> I recommend that you take a look at the Mylyn help bundle
> http://wiki.eclipse.org/DocumentationGuidelines/CrowdSourcin gExample#Mylyn
> It shows how to maintain a master TOC with anchors and links, integrating generated TOC.

Thanks for the link -- hopefully that will get me to fully automated integration including external inks.

As a bit more background, after much consideration, I'm taking the XText approach, which takes care of reintegrating everything in order nicely. I've decided that the trade off between crowdsourcing and being able to maintain the docs in SVN and easily edit them in WikiText is heavily stacked toward the latter -- I've got a ton of documentation to write and I can't imagine trying to do it off of the web. But I'm using mediawiki as my markup language so down the line I'll be able to convert it back to the wiki. I'd love to see some sort of auto update process, integrated with a compare feature (e.g. a VCS client for MediaWiki!) but that seems like it would be a pretty thorny project...I'm not even sure that the wiki server side has an API that could be used for that -- you might end up having to spoof a regular user which is fraught with difficulties.

Anyway the XText approach is really cool, because you can fragment the document in any way you want. You could use this to allow other developers to override and add to sections product specific documentation for example at build time. Then of course it generates the TOC, etc.. based on the final assembled documentation. For those who haven't taken a look at their customBuild.xml you should as it is is really nice example (and there are plenty of others i the Eclipse world) of ant done well. The project structure looks a bit intimidating at first, but its actually super easy to modify for your own uses. I just:

1. Grabbed the existing structure into my project.
2. Changed all of the XText specific stuff for my project.
3. Changed the targets from textile to mediawiki.
3. Replaced the contents of doc with my own mediakwiki files and added the myproject-index.txt contents file.

For those interested, my project is at cvsroot/modeling org.eclipse.amp/org.eclipse.amp/doc/org.eclipse.amp.doc

Quote:
> >
> > Second, I wonder if anyone has built a docbook2html or wiki2html target
> > that separates the html into separate pages for say each h1 / =blah=
> > level heading? My docs are getting large and I don't want users to have
> > to download dozens of images and 30 pages of text everytime they go to
> > the docs page.
>
> This is easy to do either with WikiText directly or by using DocBook XSL chunking.

I think I'd like to do it in XSL as I want to be able to maintain it at the presentation level -- for example, it would be nice to be able to fragment at different section levels as the content per section gets bigger. And there might be different uses for which different level of segmentation make more sense..

So, I have to ask, I didn't actually find it "easy" :), in fact I could get it to work. Do you (or anyone out there) know of any projects using XSL chunking that I could take a look at? Xtext AFAICT isn't doing any chunking.

cheers,

Miles

Report message to a moderator

Re: [wikitext] Embedding links, etc.. [message #601283 is a reply to message #601207]

Tue, 27 April 2010 21:46

Miles Parker

Messages: 1341
Registered: July 2009

Senior Member

Miles Parker wrote on Fri, 23 April 2010 13:58
> So, I have to ask, I didn't actually find it "easy" :), in fact I could get it to work. Do you (or anyone out there) know of any projects using XSL chunking that I could take a look at?

I figured this out. I think I must have had something messed up in the configuration as the basic steps I was taking were correct. For others, you just:

1. Copy chunk.xsl, chunk-common.xsl and chunk-code.xsl into your styles dir
2. In html.xss, change docbook.xsl to chunk.xsl
3. Customize the chunking according to the docbook chunking docs.

One change you'll want to make to match with the xtext structure is to get rid of the base.dir attribute. See the preceeding message for a reference to the amp project implementation.

Report message to a moderator

Previous Topic:	team planning -- worked
Next Topic:	How to prevent resources from fading away too quickly?

Goto Forum:

-=] Back to Top [=-

[ Syndicate this forum (XML) ] [

]

Current Time: Fri Apr 19 03:42:07 GMT 2024

.:: Contact :: Home ::.

Breadcrumbs

Sign up to our Newsletter