Mailing List Archive

EMMEL Thomas wrote:
> Hi,
>
> I wonder whether there is an easy way to add an own element to the dtd
> like <span> or <div>?
> I wrote the main part in html that is converted on the fly to xml and
> back to html. However, I use some special css-tricks to add layout to
> the output like 'element:hover'-tips etc. by using <span class=...>.
> The problem is that this doesnt work in the xml-parts I use more and more.
> Running 'forrest run' the output is as expected since there is no
> xml-checking done.

Forrest is not intended to be a web publishing framework, as such it
does not support many of the web-centric layout markup.

You can fudge things so that it will do what you want, but if you want a
web publishing framework Forrest may not be the right tool for you.

Having said that. The easiest way to achieve what you want is to turn
off validation for the pages you want to fudge. However, be aware that
validation is there for a reason. By turning it off you run the risk of
breaking some of the other output formats. You need to decide if this is
a problem for you or not.

To control validation see
http://forrest.apache.org/docs_0_80/validation.html#xml_validation

A better approach is to add your own DTD that supports the elements you
want to use, see
http://forrest.apache.org/docs_0_90/your-project.html#adding_new_content_type

Adding your own DTD with transformation to XDoc means you still validate
the XML, which will prevent one set of funnies (i.e. badly formed XML),
but it still leaves you open to breaking some output formats if your XSL
keeps non-XDoc elements in the output.

Ross

Ross,

Ok, I solved it by adding an own DTD for my project, which was a bit
hard since there are several informations in the forrest docs which are
hard to follow if you dont decide to read the whole docs.
In addition I managed the XInclude-stuff this way I was looking long for
but hesitated to try it for the same reasons above.
I took several informations from the location you gave and the
mailing-list where I wonder in the end how this ever could have worked
for anyone else (see
http://www.mail-archive.com/user@forrest.apache.org/msg02344.html) since
I had to change some small issues...

To the other point:
Why should Forrest not intended to be a web publishing framework???
While it generates the framework we (I) need for a technical
documentation it could be still open for some layout I think.
Of course it should not compare to sites written by some CSS-guru but
it creates html and therefore it can create html that can use CSS
together with all sort of additions this gives us, e.g. layout for
printouts or for users with a handicap and so on.

Kind regards and thanks for a very good work

Thomas

Ross Gardler schrieb:
> EMMEL Thomas wrote:
>> Hi,
>>
>> I wonder whether there is an easy way to add an own element to the dtd
>> like <span> or <div>?
>> I wrote the main part in html that is converted on the fly to xml and
>> back to html. However, I use some special css-tricks to add layout to
>> the output like 'element:hover'-tips etc. by using <span class=...>.
>> The problem is that this doesnt work in the xml-parts I use more and
>> more.
>> Running 'forrest run' the output is as expected since there is no
>> xml-checking done.
>
> Forrest is not intended to be a web publishing framework, as such it
> does not support many of the web-centric layout markup.
>
> You can fudge things so that it will do what you want, but if you want a
> web publishing framework Forrest may not be the right tool for you.
>
> Having said that. The easiest way to achieve what you want is to turn
> off validation for the pages you want to fudge. However, be aware that
> validation is there for a reason. By turning it off you run the risk of
> breaking some of the other output formats. You need to decide if this is
> a problem for you or not.
>
> To control validation see
> http://forrest.apache.org/docs_0_80/validation.html#xml_validation
>
> A better approach is to add your own DTD that supports the elements you
> want to use, see
> http://forrest.apache.org/docs_0_90/your-project.html#adding_new_content_type
>
>
> Adding your own DTD with transformation to XDoc means you still validate
> the XML, which will prevent one set of funnies (i.e. badly formed XML),
> but it still leaves you open to breaking some output formats if your XSL
> keeps non-XDoc elements in the output.
>
> Ross

EMMEL Thomas wrote:
> Ok, I solved it by adding an own DTD for my project, which was a bit
> hard since there are several informations in the forrest docs which are
> hard to follow if you dont decide to read the whole docs.

Patches welcome and appreciated.

> I took several informations from the location you gave and the
> mailing-list where I wonder in the end how this ever could have worked
> for anyone else (see
> http://www.mail-archive.com/user@forrest.apache.org/msg02344.html) since
> I had to change some small issues...

Don't keep it to yourself, share the info. Patches welcome - this is a
community project.

> To the other point:
> Why should Forrest not intended to be a web publishing framework???

The first line of our home page says "Apache Forrest is a publishing
framework that transforms input from various sources into a unified
presentation in one or more output formats."

Web is only one output format. It *can* be used as a web publishing
framework, and many people do use it as such. However, that was not why
it was created. If someone wants a web publication framework and does
not intend to publish in any format there are other, arguably better, tools.

Your fist engagement with this project was to ask how to do something
that only makes sense on the web and as a result you have already had to
define a new DTD and XSL stylesheet. Why? Because Forrest is not a web
publication framework, but a general purpose publication framework.

Ross

Ross, Just to get my understanding right:

<snip/>
>
> A better approach is to add your own DTD that supports the elements you
> want to use, see
> http://forrest.apache.org/docs_0_90/your-project.html#adding_new_content_type
>
>
> Adding your own DTD with transformation to XDoc means you still validate
> the XML, which will prevent one set of funnies (i.e. badly formed XML),
> but it still leaves you open to breaking some output formats if your XSL
> keeps non-XDoc elements in the output.


The transformation is from myDTD to Forrest's internal format.
The <span> tag still isn't present in xdoc.

So this works because Forrest isn't so strict to validate the xml further
down its processing pipeline. One may use the same feature (bug?) writing
an input plugin thus bypassing Forrests validation of its internal format.

With other words:
Forrest validates the input files when read "from disk"
but afterwards is "sloppy" about validation and passes
unknown tags on to the output.

In the end <span> gets passed on to HTML and the browser knows how to
handle it. Luckily. With a the tag named <funny-span> your content would
not show up: browsers tend to ignore unknown tags (1).

Breaking other output formats means that either further processing steps
fail because of unknown tags or these tags get ignored.

Am I right?

This is because Forrest's xdoc is not very "rich" semantically.
A switch to XHTML as internal format is envisioned for Forrest.
This will offer more flexibility.


Cheers
Johannes

(1) You may see this effect when inspecting any HTML page of your Forrest
site with "body-" prefixed: there are <tocitems> in the source that
the browser ignore.


>
> Ross
>

--
User Interface Design GmbH, Ludwigsburg, Germany
Phone/Fax +49 7141 37700-46/-99, Mobile +49 170 4914567
E-mail johannes.schaefer@uidesign.de * www.uidesign.de

Offices:
Martin-Luther-Straße 57-59, D-71636 Ludwigsburg
Truderinger Strasse 330, D-81825 Muenchen
Friedrichsring 46, D-68161 Mannheim

Legal information according to EHUG:
User Interface Design GmbH; Managing Directors: Dr. Claus Goerner,
Franz Koller; Head office: Ludwigsburg; Commercial register of the
local court of Stuttgart, Germany, HRB 205519

Ross Gardler schrieb:
> EMMEL Thomas wrote:
>> Ok, I solved it by adding an own DTD for my project, which was a bit
>> hard since there are several informations in the forrest docs which
>> are hard to follow if you dont decide to read the whole docs.
>
> Patches welcome and appreciated.
>
>> I took several informations from the location you gave and the
>> mailing-list where I wonder in the end how this ever could have worked
>> for anyone else (see
>> http://www.mail-archive.com/user@forrest.apache.org/msg02344.html)
>> since I had to change some small issues...
>
> Don't keep it to yourself, share the info. Patches welcome - this is a
> community project.

Never thought such small changes would help... :-), specially when
they come from one like me not intended to be a XML expert at all.

But of course I will attach my DTD to help others.
Should I add something to the documentation here as well?
The catalog.xcat-entry is here
>>>>snip
<!-- my own dtd -->
<public publicId="-//Your Company Name//Document w XInclude DTD 2.1//EN"
uri="document-xinclude-v21.dtd"/>
<<<snip

In addition if anyone have problems getting the <span> element working I
may help, cause I think there are some other changes I made last year to
the xsl that creates xml from html where I need to do a diff to find it...
I hope next week there is some time to look for that.


For me it is always hard to follow the documentation of forrest since
there is some flow-chart or something like this missing. In other points
I always have to play with and test things to find the point where I
need to do changes for my purpose.
>
>> To the other point:
>> Why should Forrest not intended to be a web publishing framework???
>
> The first line of our home page says "Apache Forrest is a publishing
> framework that transforms input from various sources into a unified
> presentation in one or more output formats."
>
> Web is only one output format. It *can* be used as a web publishing
> framework, and many people do use it as such. However, that was not why
> it was created. If someone wants a web publication framework and does
> not intend to publish in any format there are other, arguably better,
> tools.

Yes, but getting PDF as well is one of the big points where I dont like
to start with a huge programming package just to manage one time in ten
years a documentation of 100 pages.
And thus I found forrest one of the best tools around.

BTW, is there any progress in the last time to bring more features and
fixes to the PDF-output? Like table-sizes, the problem with the pictures
that are too high in aspect-ratio and so on...
>
> Your fist engagement with this project was to ask how to do something
> that only makes sense on the web and as a result you have already had to
> define a new DTD and XSL stylesheet. Why? Because Forrest is not a web
> publication framework, but a general purpose publication framework.

Accepted and dont be so 'hard' (:-)) with those who just try to use it...

>
> Ross

Thanks and kind regards

Thomas

Johannes Schaefer wrote:
> Ross, Just to get my understanding right:
>
> <snip/>
>>
>> A better approach is to add your own DTD that supports the elements
>> you want to use, see
>> http://forrest.apache.org/docs_0_90/your-project.html#adding_new_content_type
>>
>>
>> Adding your own DTD with transformation to XDoc means you still
>> validate the XML, which will prevent one set of funnies (i.e. badly
>> formed XML), but it still leaves you open to breaking some output
>> formats if your XSL keeps non-XDoc elements in the output.
>
>
> The transformation is from myDTD to Forrest's internal format.
> The <span> tag still isn't present in xdoc.
>
> So this works because Forrest isn't so strict to validate the xml further
> down its processing pipeline. One may use the same feature (bug?)
> writing an input plugin thus bypassing Forrests validation of its
> internal format.
>
> With other words:
> Forrest validates the input files when read "from disk"
> but afterwards is "sloppy" about validation and passes
> unknown tags on to the output.
>
> In the end <span> gets passed on to HTML and the browser knows how to
> handle it. Luckily. With a the tag named <funny-span> your content would
> not show up: browsers tend to ignore unknown tags (1).
>
> Breaking other output formats means that either further processing steps
> fail because of unknown tags or these tags get ignored.
>
> Am I right?

You are 100% correct :-)

Ross

>
> This is because Forrest's xdoc is not very "rich" semantically.
> A switch to XHTML as internal format is envisioned for Forrest.
> This will offer more flexibility.
>
>
> Cheers
> Johannes
>
> (1) You may see this effect when inspecting any HTML page of your Forrest
> site with "body-" prefixed: there are <tocitems> in the source that
> the browser ignore.
>
>
>>
>> Ross
>>
>

EMMEL Thomas wrote:
> Ross Gardler schrieb:
>> EMMEL Thomas wrote:
>>> Ok, I solved it by adding an own DTD for my project, which was a bit
>>> hard since there are several informations in the forrest docs which
>>> are hard to follow if you dont decide to read the whole docs.
>>
>> Patches welcome and appreciated.
>>
>>> I took several informations from the location you gave and the
>>> mailing-list where I wonder in the end how this ever could have
>>> worked for anyone else (see
>>> http://www.mail-archive.com/user@forrest.apache.org/msg02344.html)
>>> since I had to change some small issues...
>>
>> Don't keep it to yourself, share the info. Patches welcome - this is a
>> community project.
>
> Never thought such small changes would help... :-),

All the small changes add up to a full knowledge base. Thanks for taking
the time to document this in our archives - now the next person have
this problem won't need to work it out for themselves.

> But of course I will attach my DTD to help others.
> Should I add something to the documentation here as well?

Any clarifications to our docs are greatly appreciated. In some ways
they are better than code contributions since Forrest newbies are better
equipped to understand what problems newcomers face. Code becomes easy
with familiarity, without documentation it's hard to become familiar.
Those familiar often don't find the time to write documentation.

The only way to break this is to encourage improvements to our docs from
newcomers (no matter how "small" it may appear to be).

>>> To the other point:
>>> Why should Forrest not intended to be a web publishing framework???
>>
>> The first line of our home page says "Apache Forrest is a publishing
>> framework that transforms input from various sources into a unified
>> presentation in one or more output formats."
>>
>> Web is only one output format. It *can* be used as a web publishing
>> framework, and many people do use it as such. However, that was not
>> why it was created. If someone wants a web publication framework and
>> does not intend to publish in any format there are other, arguably
>> better, tools.
>
> Yes, but getting PDF as well is one of the big points where I dont like
> to start with a huge programming package just to manage one time in ten
> years a documentation of 100 pages.
> And thus I found forrest one of the best tools around.

That's exactly my point. The more you tweak things to work in HTML, the
more likely you are to break things in PDF or some other output format.

See Johannes' more complete explanation of why such customisations may
break other output formats (in this thread).

> BTW, is there any progress in the last time to bring more features and
> fixes to the PDF-output? Like table-sizes, the problem with the pictures
> that are too high in aspect-ratio and so on...

I think the image size issue is fixed (although I've not checked JIRA).
The table layout is a limitation of FOP, but I think this has been fixed
in the new FOP release and Ferdinand is currently working on upgrading
to this new FOP (although progress seems to have halted at present).

If there are other issues you are having please add them to the issue
tracker.

>> Your fist engagement with this project was to ask how to do something
>> that only makes sense on the web and as a result you have already had
>> to define a new DTD and XSL stylesheet. Why? Because Forrest is not a
>> web publication framework, but a general purpose publication framework.
>
> Accepted and dont be so 'hard' (:-)) with those who just try to use it...

Sorry, I'm not intending to be "hard" I'm just trying to ensure you know
the potential problems with fudging things in the way I was proposing.
I'd hate for you to become tied to Forrest and then find that it doesn't
work as expected because you exploited a "feature" like this. As long as
you are aware of the potential drawbacks you can do what you like ;-)

Ross