You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@forrest.apache.org by Linda Rose <li...@cox.net> on 2004/10/15 23:24:12 UTC
Question from a newbie
I'm new to this group ... apologies in advance if this is a stupid question.
I've just started looking at Forrest (at the suggestion of a programmer). My
background is in commercial software documentation, where we used Framemaker
to create online and print software documentation. I've recently changed
positions to one in a University, where I'm looking at Forrest to do
documentation.
My questions are: what tool do you use to author your content in? Can I use
XML output from Framemaker?
Thanks,
Linda
Re: Framemaker support (was Re: Question from a newbie)
Posted by Clay Leeds <cl...@medata.com>.
On Oct 15, 2004, at 3:22 PM, Ross Gardler wrote:
> Linda Rose wrote:
>> Thanks for the reply. I tried using a Framemaker xml file and the
>> build
>> failed with a "not valid xml document."
>> Do you know what the files in http://forrest.apache.org were authored
>> in?
>> (Please don't say vi.)
>
> I'm sure someone uses Vi, but you'll be pleased to hear you don;t have
> to.
I've used vi for it, but I prefer to use something like BBEdit (Mac),
TextPad, or eclipse.org's wonderful open source (and FREE as in beer!)
text editor.
> Forrest supports a wide range of input formats and therefore supports
> a wide range of editing tools. Some examples are XHTML, HTML, Open
> Office, Docbook, SVG and many more. Most of the documents in
> forrest.apache.org and in the seed site (generated with forrest seed)
> are in a format we call XDoc. This is an internal format used within
> Forrest.
>
> DTD's for XDOC are available in
> FORRREST_HOME/src/core/context/resources/schema/dtd/
>
> I am not familiar with Framemaker but a quick glance at its feature
> set seems to imply that it can be used to edit any XML document once
> given a DTD. TO do this in a true WYSIWYG environment would, most
> likely require some configuration of Framemaker. I'm afraid I do not
> know how to do that, maybe someone else here can help.
>
> If framemaker can export in any of our supported formats then that
> would probably be the easiest route.
I suspect FrameMaker has the ability to customize output as well.
However, The following suggestion is even better:
> The final option would be to add support to Forrest for Framemakers
> native format (I am assuming it saves in an XML format). If you have
> any XSL skills (or can get a Comp Sci student, since you are now in a
> University, to do it as a project for their course we will be happy to
> help you/them do that).
>
> Ross
Why is this better (IMO)? Because it means that you would be
contributing to the Apache Forrest Project, the ability to read
FrameMaker files, which would mean that all future Forrest users would
benefit. This would be huge!
Here's a sample structure for a Forrest page:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Barcode4J Documentation Overview</title>
<authors>
<person id="cleeds" name="Web Maestro Clay"
email="the_webmaestro@users.sourceforge.net"/>
</authors>
</header>
<body>
<section>
<title>Introduction</title>
<p>This page describes the documentation structure for
<strong>MyProject</strong>.</p>
</section>
<section>
<title>MyProject Documentation Links</title>
<dl>
<dt><link href="MyProject.html">The MyProject Format</link></dt>
<dd>describes the XML format used by <strong>MyProject</strong>
to define MyProject items. It also contains notes about the message
format supported by each symbology.</dd>
<dt><link href="site:output-formats.html">MyProject Output
Formats</link></dt>
<dd>gives information about the various output formats
supported by <strong>MyProject</strong> and tells you how to implement
additional MyProject output formats.</dd>
<dt><link href="site:design">Design</link></dt>
<dd>describes how <strong>MyProject</strong> was designed to
implement and configure MyProject using XML, in a way that the whole
package can easily be integrated into a bigger work.</dd>
</dl>
<section>
<title>Scenarios</title>
<p>These pages show Use Cases for generating
<strong>MyProject</strong>:</p>
<dl>
<dt><link href="site:xsl-fo">XSL-FO</link></dt>
<dd>shows a use case for generating barcodes in <jump
href="ext:svg">SVG format</jump> format for <jump
href="ext:xsl-fo">XSL-FO</jump> documents.</dd>
<dt><link href="svg-dom.html">SVG DOM</link></dt>
<dd>describes the generation of an <jump href="ext:svg">SVG
format</jump> barcode in Java.</dd>
</dl>
</section>
</section>
</body>
</document>
Web Maestro Clay
--
Clay Leeds - <cl...@medata.com>
Webmaster/Developer - Medata, Inc. - <http://www.medata.com/>
PGP Public Key: <https://mail.medata.com/pgp/cleeds.asc>
Framemaker support (was Re: Question from a newbie)
Posted by Ross Gardler <rg...@apache.org>.
Linda Rose wrote:
> Thanks for the reply. I tried using a Framemaker xml file and the build
> failed with a "not valid xml document."
> Do you know what the files in http://forrest.apache.org were authored in?
> (Please don't say vi.)
I'm sure someone uses Vi, but you'll be pleased to hear you don;t have to.
Forrest supports a wide range of input formats and therefore supports a
wide range of editing tools. Some examples are XHTML, HTML, Open Office,
Docbook, SVG and many more. Most of the documents in forrest.apache.org
and in the seed site (generated with forrest seed) are in a format we
call XDoc. This is an internal format used within Forrest.
DTD's for XDOC are available in
FORRREST_HOME/src/core/context/resources/schema/dtd/
I am not familiar with Framemaker but a quick glance at its feature set
seems to imply that it can be used to edit any XML document once given a
DTD. TO do this in a true WYSIWYG environment would, most likely require
some configuration of Framemaker. I'm afraid I do not know how to do
that, maybe someone else here can help.
If framemaker can export in any of our supported formats then that would
probably be the easiest route.
The final option would be to add support to Forrest for Framemakers
native format (I am assuming it saves in an XML format). If you have any
XSL skills (or can get a Comp Sci student, since you are now in a
University, to do it as a project for their course we will be happy to
help you/them do that).
Ross
Re: Question from a newbie
Posted by David Crossley <cr...@apache.org>.
Linda Rose wrote:
>
> Thanks for the reply. I tried using a Framemaker xml file and the build
> failed with a "not valid xml document."
Is your "Framemaker XML" in the Forrest document format?
As Clay said, see the Samples in the demo application
which is delivered with Forrest. You cannot just try to
force Forrest to read any structure. That said, if you
do have documents is a certain structure then Forrest
can be configured to use it. See the "advanced" section
of the "Using Forrest" document.
> Do you know what the files in http://forrest.apache.org were authored in?
> (Please don't say vi.)
It depends who the author is and their skills.
I definitely use "vi" sometimes. Other times i use
a proper xml editor such as "XXE".
See http://forrest.apache.org/docs/catalog.html
for the variety of "XML editors" that people have
reported using.
--
David Crossley
Re: Question from a newbie
Posted by Linda Rose <li...@cox.net>.
Hi Clay,
Thanks for the reply. I tried using a Framemaker xml file and the build
failed with a "not valid xml document."
Do you know what the files in http://forrest.apache.org were authored in?
(Please don't say vi.)
Linda
----- Original Message -----
From: "Clay Leeds" <cl...@medata.com>
To: <us...@forrest.apache.org>
Sent: Friday, October 15, 2004 2:35 PM
Subject: Re: Question from a newbie
> On Oct 15, 2004, at 2:24 PM, Linda Rose wrote:
> > I'm new to this group ... apologies in advance if this is a stupid
> > question.
> > I've just started looking at Forrest (at the suggestion of a
> > programmer). My
> > background is in commercial software documentation, where we used
> > Framemaker
> > to create online and print software documentation. I've recently
> > changed
> > positions to one in a University, where I'm looking at Forrest to do
> > documentation.
> >
> > My questions are: what tool do you use to author your content in? Can
> > I use
> > XML output from Framemaker?
> >
> > Thanks,
> >
> > Linda
>
> I don't know if Framemaker exports would work. They may, I just don't
> know.
>
> I'm not a FORREST committer (i.e., I'm not an expert), but if you
> download FORREST and get it running, you should be able to do:
>
> forrest seed
>
> which will generate a Forrest site. Then do a:
>
> open build/site/index.html
>
> to open it in a browser. Once you've done that, you can see what the
> site looks like. Then you should be able to do a:
>
> cd src/documentation/content/xdocs
>
> to change to the source XML directory. From there, "samples/" contains
> a bunch of sample files you can look at. Included in there is an
> example of an OpenOffice.org1.1.2 file[1] which we are beginning to use
> to generate online documentation. In fact, I believe that particular
> file itself was generated from an OpenOffice.org Writer (.sxw)
> document.
>
> [1]
> http://forrest.apache.org/docs/oowriter.html
>
> Web Maestro Clay
> --
> Clay Leeds - <cl...@medata.com>
> Webmaster/Developer - Medata, Inc. - <http://www.medata.com/>
> PGP Public Key: <https://mail.medata.com/pgp/cleeds.asc>
>
>
Re: Question from a newbie
Posted by Clay Leeds <cl...@medata.com>.
On Oct 15, 2004, at 2:24 PM, Linda Rose wrote:
> I'm new to this group ... apologies in advance if this is a stupid
> question.
> I've just started looking at Forrest (at the suggestion of a
> programmer). My
> background is in commercial software documentation, where we used
> Framemaker
> to create online and print software documentation. I've recently
> changed
> positions to one in a University, where I'm looking at Forrest to do
> documentation.
>
> My questions are: what tool do you use to author your content in? Can
> I use
> XML output from Framemaker?
>
> Thanks,
>
> Linda
I don't know if Framemaker exports would work. They may, I just don't
know.
I'm not a FORREST committer (i.e., I'm not an expert), but if you
download FORREST and get it running, you should be able to do:
forrest seed
which will generate a Forrest site. Then do a:
open build/site/index.html
to open it in a browser. Once you've done that, you can see what the
site looks like. Then you should be able to do a:
cd src/documentation/content/xdocs
to change to the source XML directory. From there, "samples/" contains
a bunch of sample files you can look at. Included in there is an
example of an OpenOffice.org1.1.2 file[1] which we are beginning to use
to generate online documentation. In fact, I believe that particular
file itself was generated from an OpenOffice.org Writer (.sxw)
document.
[1]
http://forrest.apache.org/docs/oowriter.html
Web Maestro Clay
--
Clay Leeds - <cl...@medata.com>
Webmaster/Developer - Medata, Inc. - <http://www.medata.com/>
PGP Public Key: <https://mail.medata.com/pgp/cleeds.asc>
Re: Question from a newbie
Posted by David Crossley <cr...@apache.org>.
Linda Rose wrote:
> I'm new to this group ... apologies in advance if this is a stupid question.
> I've just started looking at Forrest (at the suggestion of a programmer). My
> background is in commercial software documentation, where we used Framemaker
> to create online and print software documentation. I've recently changed
> positions to one in a University, where I'm looking at Forrest to do
> documentation.
>
> My questions are: what tool do you use to author your content in?
I just added an FAQ to answer that:
http://forrest.apache.org/faq.html#edit-content
> Can I use XML output from Framemaker?
Does this output have a well-defined structure?
If so, then the answer is yes. Follow the techniques
described at
http://forrest.apache.org/docs/your-project.html#sitemap.xmap
However, you should first get started with Forrest
and then move on to such advanced applications.
--
David Crossley