Home » Eclipse Projects » Platform - User Assistance (UA) » General help documentation development question
| |
Re: General help documentation development question [message #472308 is a reply to message #472302] |
Fri, 08 February 2008 08:32 |
Francis Upton IV Messages: 472 Registered: July 2009 Location: Oakland, CA |
Senior Member |
|
|
I have similar goals, and all of my documentation source is in DocBook.
With docbook you can generate just about anything (including Eclipse
help files). It has worked very well for me, and I have had my
documentation there for years, even before I migrated to eclipse, I used
to generate Java help from the docbook.
Pete Ellis wrote:
> Hello all,
>
> We are looking to integrate help documentation into our Eclipse based tool.
> We are searching for an efficient means of doing this that allows us to:
> a) Develop and maintain our documentation in an efficient way (i.e., a
> traditional word processor)
> b) Obtain the HTML files at the level of granularity necessary to populate
> the built-in Eclipse help services, including infopop content, and
> c) Publish traditional paper documentation (in the form of manuals) that we
> would optionally make available to our customers
>
> As we are currently an MS Word house, that was my first area of
> investigation... however it appears that MS Word has no native means of
> breaking up a documents content into individual HTML files. Thus, a 100
> page reference manual would be exported to a single giant HTML file, which
> is of much less use in the Eclipse help environment.
>
> So my questions are:
>
> 1) What techniques/products do others use to accomplish these goals?
>
> 2) What mechanism does the Eclipse organization use to author and deploy
> its own help content?
>
> Many thanks,
> -Pete
>
>
>
Platform UI Committer for Common Navigator
http://wiki.eclipse.org/index.php/Common_Navigator_Framework
http://help.eclipse.org/galileo/topic/org.eclipse.platform.d oc.isv/guide/cnf.htm
|
|
| |
Re: General help documentation development question [message #472429 is a reply to message #472426] |
Wed, 02 April 2008 15:41 |
Eclipse User |
|
|
|
Originally posted by: nospam_kowalskilee.gmail.com
Hi Marcus,
You wrote "traditional word processors". Would you list which ones you
are focused on? I mean, is it Word or FrameMaker or what else?
In general, it will not be easy to convert from an unstructured document
environment to a structured document environment. However, if you are
using FrameMaker, there is a product called "Mif2Go" that people are
using today to go from their FrameMaker mif files to generate the
Eclipse help files.
If your traditional word processor is Word, there might be some
conversion tools available to go from Word to DITA XML (which is an XML
format comparable to DocBook). From DITA XML, you can go to Eclipse help
like you do from DocBook.
One thing to think about is whether you mean to do a one-time conversion
and take all your traditional-created files to DocBook, and then
continue from that point in time with DocBook *or* do you mean to
continue authoring in the traditional word processor and generate the
Eclipse help files at build times. The answer to that will guide what
tools will best suit your need.
Best regards,
Lee Anne
Marcus Storre wrote:
> Hello,
>
> Currently we try to convert our documentation in DocBook as well, cause
> we like the possibility to generate easily any format we want to,
> especially the eclipse help files. We already tested it, and it really
> worked fine.
>
> Unfortunatly its not as easy to convert our current documentation
> (written with tradtional word processors) to DocBook, as it is to
> convert from DocBook to everything else.
>
> How do you generate your DocBook files? Do you write your documentation
> already in DocBook? If so, which Software can you recommend? Are there
> any effective alternatives to DocBook to get the Eclipse Help System
> files out of a traditional word processor?
>
> Thanks in advance,
> Marcus
>
>
>
|
|
|
Re: General help documentation development question [message #472431 is a reply to message #472429] |
Thu, 03 April 2008 11:08 |
Marcus Messages: 16 Registered: July 2009 |
Junior Member |
|
|
Hi Lee Anne,
thank you for your fast reply. We started to evaluate a process to
generate DocBooks from .odt files, since OpenOffice 2.3.1 already has an
implemented DocBook Filter. Unfortunately we did not really receive the
results we hoped for. We also successful converted sxw files, but we try
to avoid this format.
Our support is documenting in Word and MindManager, so we are looking for
a persistent solution to generate Eclipse Help Files (or other formats)
out of a .doc document. MindManager is able to export in .doc so a
suitable solution for Word would be as fine as it would be for
MindManager. If there is no pleasant way to handle this, a one
time-conversion and working with DocBook - Editors might be an
alternative, but so far we try to avoid this as well.
DITA seems to be a decent alternative to DocBook, and we will consider
this format to replace DocBook, if it is easier to generate a structured
document environment from it that fits our needs.
Do you might have any suggestions, what a decent way could look like for
generating DocBook/DITA from .doc or .odt?
Sincerely,
Marcus
Lee Anne wrote:
> Hi Marcus,
> You wrote "traditional word processors". Would you list which ones you
> are focused on? I mean, is it Word or FrameMaker or what else?
> In general, it will not be easy to convert from an unstructured document
> environment to a structured document environment. However, if you are
> using FrameMaker, there is a product called "Mif2Go" that people are
> using today to go from their FrameMaker mif files to generate the
> Eclipse help files.
> If your traditional word processor is Word, there might be some
> conversion tools available to go from Word to DITA XML (which is an XML
> format comparable to DocBook). From DITA XML, you can go to Eclipse help
> like you do from DocBook.
> One thing to think about is whether you mean to do a one-time conversion
> and take all your traditional-created files to DocBook, and then
> continue from that point in time with DocBook *or* do you mean to
> continue authoring in the traditional word processor and generate the
> Eclipse help files at build times. The answer to that will guide what
> tools will best suit your need.
> Best regards,
> Lee Anne
|
|
|
Re: General help documentation development question [message #472512 is a reply to message #472431] |
Fri, 04 April 2008 14:56 |
Eclipse User |
|
|
|
Originally posted by: nospam_kowalskilee.gmail.com
Hi Marcus,
I did some sleuthing on the DITA YahooGroup and I found this company's
tool: Information Mapping's Content Mapper tool mentioned:
http://www.infomap.com/index.cfm/Software/ContentMapper
That page says it is a "Microsoft Word-based XML authoring tool" *and*
that it has been configured with both DocBook and DITA.
I also found this company's products mentioned related to Word and XML
and Word and DITA:
http://www.invisionresearch.com/products.html
It has two products that look promising for a goal of authoring in Word
and then getting DITA and/or DocBook output:
Xpress Author http://www.invisionresearch.com/xpress.html
XPress Author sounds like it is an add-on to Word, where you work in
Word and it maps to an XML DTD or Schema. From the page, it sounds like
it might work with either DocBook or DITA.
Xpress DITA Studio http://www.invisionresearch.com/dita.html
Xpress DITA Studio seems to be a combo of Xpress Author (Word + their
XML add-on) *and* the tooling oriented to DITA concepts (DITA maps, DITA
DTD/schema, etc)
Then I found this company's tool: Information Mapping's Content Mapper
tool: http://www.infomap.com/index.cfm/Software/ContentMapper
That page says it is a "Microsoft Word-based XML authoring tool".
FYI, there's an active group of DITA exploiters on a YahooGroup named
dita-users. The group's home is here:
http://tech.groups.yahoo.com/group/dita-users/
There are folks who are interested in a Word->DITA solution that
participate on that list, as well as people who are experienced in
DocBook also--so you'd benefit from tapping them as a resource.
This posting at the dita-users group mentions the pricing for both
In.vision products and Information Mapping's Content Mapper product:
http://tech.groups.yahoo.com/group/dita-users/message/9051
I don't have experience with MindManager, so I cannot speak to that one.
Hope this helps!
Lee Anne
Marcus Storre wrote:
> Hi Lee Anne,
>
> thank you for your fast reply. We started to evaluate a process to
> generate DocBooks from .odt files, since OpenOffice 2.3.1 already has an
> implemented DocBook Filter. Unfortunately we did not really receive the
> results we hoped for. We also �successful� converted sxw files, but we
> try to avoid this format.
>
> Our support is documenting in Word and MindManager, so we are looking
> for a persistent solution to generate Eclipse Help Files (or other
> formats) out of a .doc document. MindManager is able to export in .doc
> so a suitable solution for Word would be as fine as it would be for
> MindManager. If there is no pleasant way to handle this, a one
> time-conversion and working with DocBook - Editors might be an
> alternative, but so far we try to avoid this as well.
>
> DITA seems to be a decent alternative to DocBook, and we will consider
> this format to replace DocBook, if it is easier to generate a structured
> document environment from it that fits our needs.
>
> Do you might have any suggestions, what a decent way could look like for
> generating DocBook/DITA from .doc or .odt?
>
> Sincerely,
> Marcus
>
>
> Lee Anne wrote:
>
>> Hi Marcus,
>
>> You wrote "traditional word processors". Would you list which ones you
>> are focused on? I mean, is it Word or FrameMaker or what else?
>
>> In general, it will not be easy to convert from an unstructured
>> document environment to a structured document environment. However, if
>> you are using FrameMaker, there is a product called "Mif2Go" that
>> people are using today to go from their FrameMaker mif files to
>> generate the Eclipse help files.
>
>> If your traditional word processor is Word, there might be some
>> conversion tools available to go from Word to DITA XML (which is an
>> XML format comparable to DocBook). From DITA XML, you can go to
>> Eclipse help like you do from DocBook.
>
>> One thing to think about is whether you mean to do a one-time
>> conversion and take all your traditional-created files to DocBook, and
>> then continue from that point in time with DocBook *or* do you mean to
>> continue authoring in the traditional word processor and generate the
>> Eclipse help files at build times. The answer to that will guide what
>> tools will best suit your need.
>
>> Best regards,
>> Lee Anne
>
>
>
|
|
| | | | | |
Re: General help documentation development question [message #609399 is a reply to message #472302] |
Fri, 08 February 2008 08:32 |
Francis Upton IV Messages: 472 Registered: July 2009 Location: Oakland, CA |
Senior Member |
|
|
I have similar goals, and all of my documentation source is in DocBook.
With docbook you can generate just about anything (including Eclipse
help files). It has worked very well for me, and I have had my
documentation there for years, even before I migrated to eclipse, I used
to generate Java help from the docbook.
Pete Ellis wrote:
> Hello all,
>
> We are looking to integrate help documentation into our Eclipse based tool.
> We are searching for an efficient means of doing this that allows us to:
> a) Develop and maintain our documentation in an efficient way (i.e., a
> traditional word processor)
> b) Obtain the HTML files at the level of granularity necessary to populate
> the built-in Eclipse help services, including infopop content, and
> c) Publish traditional paper documentation (in the form of manuals) that we
> would optionally make available to our customers
>
> As we are currently an MS Word house, that was my first area of
> investigation... however it appears that MS Word has no native means of
> breaking up a documents content into individual HTML files. Thus, a 100
> page reference manual would be exported to a single giant HTML file, which
> is of much less use in the Eclipse help environment.
>
> So my questions are:
>
> 1) What techniques/products do others use to accomplish these goals?
>
> 2) What mechanism does the Eclipse organization use to author and deploy
> its own help content?
>
> Many thanks,
> -Pete
>
>
>
Platform UI Committer for Common Navigator
http://wiki.eclipse.org/index.php/Common_Navigator_Framework
http://help.eclipse.org/galileo/topic/org.eclipse.platform.d oc.isv/guide/cnf.htm
|
|
| |
Re: General help documentation development question [message #611102 is a reply to message #472426] |
Wed, 02 April 2008 15:41 |
Eclipse User |
|
|
|
Originally posted by: nospam_kowalskilee.gmail.com
Hi Marcus,
You wrote "traditional word processors". Would you list which ones you
are focused on? I mean, is it Word or FrameMaker or what else?
In general, it will not be easy to convert from an unstructured document
environment to a structured document environment. However, if you are
using FrameMaker, there is a product called "Mif2Go" that people are
using today to go from their FrameMaker mif files to generate the
Eclipse help files.
If your traditional word processor is Word, there might be some
conversion tools available to go from Word to DITA XML (which is an XML
format comparable to DocBook). From DITA XML, you can go to Eclipse help
like you do from DocBook.
One thing to think about is whether you mean to do a one-time conversion
and take all your traditional-created files to DocBook, and then
continue from that point in time with DocBook *or* do you mean to
continue authoring in the traditional word processor and generate the
Eclipse help files at build times. The answer to that will guide what
tools will best suit your need.
Best regards,
Lee Anne
Marcus Storre wrote:
> Hello,
>
> Currently we try to convert our documentation in DocBook as well, cause
> we like the possibility to generate easily any format we want to,
> especially the eclipse help files. We already tested it, and it really
> worked fine.
>
> Unfortunatly its not as easy to convert our current documentation
> (written with tradtional word processors) to DocBook, as it is to
> convert from DocBook to everything else.
>
> How do you generate your DocBook files? Do you write your documentation
> already in DocBook? If so, which Software can you recommend? Are there
> any effective alternatives to DocBook to get the Eclipse Help System
> files out of a traditional word processor?
>
> Thanks in advance,
> Marcus
>
>
>
|
|
|
Re: General help documentation development question [message #611104 is a reply to message #472429] |
Thu, 03 April 2008 11:08 |
Marcus Messages: 16 Registered: July 2009 |
Junior Member |
|
|
Hi Lee Anne,
thank you for your fast reply. We started to evaluate a process to
generate DocBooks from .odt files, since OpenOffice 2.3.1 already has an
implemented DocBook Filter. Unfortunately we did not really receive the
results we hoped for. We also successful converted sxw files, but we try
to avoid this format.
Our support is documenting in Word and MindManager, so we are looking for
a persistent solution to generate Eclipse Help Files (or other formats)
out of a .doc document. MindManager is able to export in .doc so a
suitable solution for Word would be as fine as it would be for
MindManager. If there is no pleasant way to handle this, a one
time-conversion and working with DocBook - Editors might be an
alternative, but so far we try to avoid this as well.
DITA seems to be a decent alternative to DocBook, and we will consider
this format to replace DocBook, if it is easier to generate a structured
document environment from it that fits our needs.
Do you might have any suggestions, what a decent way could look like for
generating DocBook/DITA from .doc or .odt?
Sincerely,
Marcus
Lee Anne wrote:
> Hi Marcus,
> You wrote "traditional word processors". Would you list which ones you
> are focused on? I mean, is it Word or FrameMaker or what else?
> In general, it will not be easy to convert from an unstructured document
> environment to a structured document environment. However, if you are
> using FrameMaker, there is a product called "Mif2Go" that people are
> using today to go from their FrameMaker mif files to generate the
> Eclipse help files.
> If your traditional word processor is Word, there might be some
> conversion tools available to go from Word to DITA XML (which is an XML
> format comparable to DocBook). From DITA XML, you can go to Eclipse help
> like you do from DocBook.
> One thing to think about is whether you mean to do a one-time conversion
> and take all your traditional-created files to DocBook, and then
> continue from that point in time with DocBook *or* do you mean to
> continue authoring in the traditional word processor and generate the
> Eclipse help files at build times. The answer to that will guide what
> tools will best suit your need.
> Best regards,
> Lee Anne
|
|
|
Re: General help documentation development question [message #611123 is a reply to message #472431] |
Fri, 04 April 2008 14:56 |
Eclipse User |
|
|
|
Originally posted by: nospam_kowalskilee.gmail.com
Hi Marcus,
I did some sleuthing on the DITA YahooGroup and I found this company's
tool: Information Mapping's Content Mapper tool mentioned:
http://www.infomap.com/index.cfm/Software/ContentMapper
That page says it is a "Microsoft Word-based XML authoring tool" *and*
that it has been configured with both DocBook and DITA.
I also found this company's products mentioned related to Word and XML
and Word and DITA:
http://www.invisionresearch.com/products.html
It has two products that look promising for a goal of authoring in Word
and then getting DITA and/or DocBook output:
Xpress Author http://www.invisionresearch.com/xpress.html
XPress Author sounds like it is an add-on to Word, where you work in
Word and it maps to an XML DTD or Schema. From the page, it sounds like
it might work with either DocBook or DITA.
Xpress DITA Studio http://www.invisionresearch.com/dita.html
Xpress DITA Studio seems to be a combo of Xpress Author (Word + their
XML add-on) *and* the tooling oriented to DITA concepts (DITA maps, DITA
DTD/schema, etc)
Then I found this company's tool: Information Mapping's Content Mapper
tool: http://www.infomap.com/index.cfm/Software/ContentMapper
That page says it is a "Microsoft Word-based XML authoring tool".
FYI, there's an active group of DITA exploiters on a YahooGroup named
dita-users. The group's home is here:
http://tech.groups.yahoo.com/group/dita-users/
There are folks who are interested in a Word->DITA solution that
participate on that list, as well as people who are experienced in
DocBook also--so you'd benefit from tapping them as a resource.
This posting at the dita-users group mentions the pricing for both
In.vision products and Information Mapping's Content Mapper product:
http://tech.groups.yahoo.com/group/dita-users/message/9051
I don't have experience with MindManager, so I cannot speak to that one.
Hope this helps!
Lee Anne
Marcus Storre wrote:
> Hi Lee Anne,
>
> thank you for your fast reply. We started to evaluate a process to
> generate DocBooks from .odt files, since OpenOffice 2.3.1 already has an
> implemented DocBook Filter. Unfortunately we did not really receive the
> results we hoped for. We also �successful� converted sxw files, but we
> try to avoid this format.
>
> Our support is documenting in Word and MindManager, so we are looking
> for a persistent solution to generate Eclipse Help Files (or other
> formats) out of a .doc document. MindManager is able to export in .doc
> so a suitable solution for Word would be as fine as it would be for
> MindManager. If there is no pleasant way to handle this, a one
> time-conversion and working with DocBook - Editors might be an
> alternative, but so far we try to avoid this as well.
>
> DITA seems to be a decent alternative to DocBook, and we will consider
> this format to replace DocBook, if it is easier to generate a structured
> document environment from it that fits our needs.
>
> Do you might have any suggestions, what a decent way could look like for
> generating DocBook/DITA from .doc or .odt?
>
> Sincerely,
> Marcus
>
>
> Lee Anne wrote:
>
>> Hi Marcus,
>
>> You wrote "traditional word processors". Would you list which ones you
>> are focused on? I mean, is it Word or FrameMaker or what else?
>
>> In general, it will not be easy to convert from an unstructured
>> document environment to a structured document environment. However, if
>> you are using FrameMaker, there is a product called "Mif2Go" that
>> people are using today to go from their FrameMaker mif files to
>> generate the Eclipse help files.
>
>> If your traditional word processor is Word, there might be some
>> conversion tools available to go from Word to DITA XML (which is an
>> XML format comparable to DocBook). From DITA XML, you can go to
>> Eclipse help like you do from DocBook.
>
>> One thing to think about is whether you mean to do a one-time
>> conversion and take all your traditional-created files to DocBook, and
>> then continue from that point in time with DocBook *or* do you mean to
>> continue authoring in the traditional word processor and generate the
>> Eclipse help files at build times. The answer to that will guide what
>> tools will best suit your need.
>
>> Best regards,
>> Lee Anne
>
>
>
|
|
| | | | |
Goto Forum:
Current Time: Mon Sep 23 14:12:08 GMT 2024
Powered by FUDForum. Page generated in 0.07358 seconds
|