$Id: guidelines.txt,v 1.20 2003/06/02 01:47:07 smith Exp $
xml-doc list guidelines
-------------------------------------------------------------------
These guidelines are sent as a Welcome message to new xml-doc
subscribers and once every four weeks to all current
subscribers. Please save these guidelines for later reference
and take a moment to review them now, including the PRIVACY
POLICY and NO-SPAM NOTICE at the end.
TABLE OF CONTENTS
-------------------------------------------------------------------
0. TOPIC GUIDELINES
1. ACCESSING THE XML-DOC WEB SITE
2. POSTING AND REPLYING TO MESSAGES
3. READING MESSAGES VIA THE WEB AND ACCESSING THE MESSAGE ARCHIVE
4. UNSUBSCRIBING, RECEIVING DIGESTS, AND PUTTING MAIL ON HOLD
5. DEALING WITH E-MAIL ATTACHMENTS
6. RECEIVING FURTHER HELP
A. PRIVACY POLICY
B. NO-SPAM NOTICE
C. NOTE ON TOPIC DRIFT, TROLLS, AND FLAMES
D. CHANGELOG
-------------------------------------------------------------------
0. TOPIC GUIDELINES
-----------------------------------------------------------------
xml-doc is for discussion of XML/SGML and document authoring,
particularly authoring of documentation for computer software
and hardware. Topics for which list members have a specific
interest include:
* XML editing applications
* Single-sourcing for multiple audiences/delivery formats
* XML-based content management systems
* DocBook and other document-oriented markup vocabularies
* Converting legacy documents
* Organizational strategies for structured authoring
* Document analysis and markup model design/refinement
* Transitioning from older (e.g. FrameMaker) environments
* Publishing (transforming and delivering XML content)
Please also take a moment to read the NOTE ON TOPIC DRIFT,
TROLLS, AND FLAMES at the end of this message.
1. ACCESSING THE XML-DOC WEB SITE
-----------------------------------------------------------------
As a member of the xml-doc mailing list, you also have access
to the xml-doc Web site:
http://groups.yahoo.com/group/xml-doc/
To use some features of the Web site, you also need to
choose a username and password and register with Yahoo Groups.
2. POSTING AND REPLYING TO MESSAGES
-----------------------------------------------------------------
To send a message to all the members of the mailing list,
e-mail it to:
xml-doc@yahoogroups.com
To post a message via the Web, visit:
http://groups.yahoo.com/post/xml-doc/
By default, when you reply to a message, the reply is sent to
all members of the list. If you want to reply just to the
author of a posted message, please specify only the author's
e-mail address in the "To:" field in your reply.
Here are a few general tips for posting and replying to
messages delivered to online mailing lists:
a. Use meaningful subject lines.
Try not to use generic, uninformative subject lines such as
"Easy question," "Help needed," "Urgent," and so on.
Instead, use meaningful subject lines that will quickly
make sense to the people whose help you are trying to get.
b. Quote only relevant parts of messages when replying.
When replying to a message, please don't quote the author's
entire message unless it's really necessary. Instead,
quote just the parts to which you are directly replying, or
quote only enough to establish a context for your reply.
c. Avoid idiomatic and colloquial English.
Be sensitive to the fact that a significant number of
subscribers to any English-language online mailing list are
non-native speakers of English. By avoiding idiomatic and
colloquial language, you ensure that your message will have
a higher degree of international readability.
Please also take a moment to read the NOTE ON TOPIC DRIFT,
TROLLS, AND FLAMES at the end of this message.
3. READING MESSAGES VIA THE WEB AND ACCESSING THE MESSAGE ARCHIVE
-----------------------------------------------------------------
All messages posted to the list are simultaneously posted to
xml-doc website and are immediately available at:
http://groups.yahoo.com/messages/xml-doc/
All messages are also automatically archived. To search
the archive, use the search box on the message page. To browse
the archive by month, visit the xml-doc main page:
http://groups.yahoo.com/group/xml-doc/
4. UNSUBSCRIBING, RECEIVING DIGESTS, AND PUTTING MAIL ON HOLD
-----------------------------------------------------------------
You can unsubscribe at any time by e-mailing a message to
xml-doc-unsubscribe@yahoogroups.com
To specify that you want to receive a digest of messages once
a day instead of receiving messages one at a time as they are
posted, send a blank e-mail message to:
xml-doc-digest@yahoogroups.com
To remain a list member, but receive no mail (for example, if
you plan to read messages by accessing the archive at the
xml-doc Web site or if you want to stop your xml-doc e-mail
while you are on a vacation), send a blank e-mail message to:
xml-doc-nomail@yahoogroups.com
To switch back from the "digest" or "no mail" settings to the
"normal" setting, send a blank e-mail message to:
xml-doc-normal@yahoogroups.com
You can also change your delivery settings from the xml-doc
Web site:
http://groups.yahoo.com/subscribe/xml-doc/
5. DEALING WITH E-MAIL ATTACHMENTS
-----------------------------------------------------------------
Any files that members attach to a message are stripped out
before the message is distributed to the list; you cannot send
or receive attachments via the list.
If you have a file you would like to make available to the
other members of the list, upload it directly to the file
sharing area of the xml-doc Web site:
http://groups.yahoo.com/files/xml-doc/
All interested members can then access or download the file at
their convenience.
6. RECEIVING FURTHER HELP
-----------------------------------------------------------------
If you have questions about the list itself and need to have
them answered by a real person, send them to:
xml-doc-owner@yahoogroups.com
Regards,
Michael Smith
xml-doc moderator and list owner
..................................................................
A. PRIVACY POLICY
-----------------------------------------------------------------
The xml-doc list moderator has a complete list of e-mail
addresses for all xml-doc subscribers, but will not provide
any subscriber e-mail addresses or personal information to any
third party, at any time, for any purpose. Yahoo Groups itself
has a separate privacy policy:
http://privacy.yahoo.com/
Read their policy carefully and make sure it is acceptable to
you. If it's not, you should unsubscribe from the list.
B. NO-SPAM NOTICE
-----------------------------------------------------------------
Please don't post messages to xml-doc that are not related
directly to XML/SGML and document authoring. Specific types of
messages that are inappropriate on the list include:
* Product or service announcements that have an excessive
amount of unobjective marketing hype
* Any "for sale" announcements; for example, if you have used
computer equipment or software you're trying to re-sell, or a
domain name you want to unload, posting an announcement to
xml-doc is not an appropriate way to try to find a buyer
You should also read the the Yahoo Terms of Service document,
which contains information about their policy toward spam, along
with other things.
http://docs.yahoo.com/info/terms/
C. NOTE ON TOPIC DRIFT, TROLLS, AND FLAMES
-----------------------------------------------------------------
Before posting or replying to a message, please remember this
list's stated purpose -- as outlined in the TOPIC GUIDELINES --
and show consideration for the fact that there are subscribers on
the list from a wide variety of professional backgrounds, and
that many people aren't going to be nearly as interested as you
might be in any particular discussion that drifts away from the
topic guidelines, no matter how important/relevant you may
personally believe the particular topic drift to be.
[0] http://www.catb.org/~esr/jargon/html/T/topic-drift.html
xml-doc is a relatively low-noise list, and relatively free
from trolls[1] and flames[2] and flame bait[3].
[1] http://www.catb.org/~esr/jargon/html/T/troll.html
[2] http://www.catb.org/~esr/jargon/html/F/flame.html
[3] http://www.catb.org/~esr/jargon/html/F/flame-bait.html
To help keep the noise level down, don't fan the flames, and
avoid feeding the trolls if/when they appear (a much better
strategy is simply to ignore them).
D. CHANGELOG
-----------------------------------------------------------------
2003-06-02 <smith@...>
* updated jargon-file URLs
2003-05-02 <smith@...>
* formatting tweak
* changed vim foldlevel
* minor reformatting
* formatting, minor updates
* topic drift, etc. section updated
2002-10-04 <smith@...>
* added section about topic drift, trolls, and flames (in another place)
* added section about topic drift, trolls, and flames
2002-07-02 <smith@...>
* changed 'DocBook and other DTDs' to 'DocBook and other markup
vocabularies'
* changed 'DTD creation' to 'markup model design'
2002-04-24 <smith@...>
* minor tweaks
* removed spam warnings
* expanded tabs
* added more no-spam warnings
* no-spam.txt: New file.
2002-04-03 <smith@...>
* fixed minor typo
2002-01-02 <smith@...>
* branches: 1.1.1; Initial revision
* added Id keyword
* New file.
// this file best viewed with Vim 6.1 or greater ;)
// vim:foldmethod=indent:foldlevel=1
I just thought I'd let you all know about some free webinars MadCap
is offering in the month of October. As you may know, MadCap makes
XML-based authoring and publishing tools.
We'd love to have you join us.
Importing FrameMaker files to Flare or Blaze
October 3 at 9am Pacific
Reserve your Webinar seat at:
https://www1.gotomeeting.com/register/667817804
What's new in Flare 4?
October 9 at 9am Pacific
Reserve your Webinar seat at:
https://www1.gotomeeting.com/register/562186940
Planning the move to Flare or Blaze
October 15 at 9am Pacific
Reserve your Webinar seat at:
https://www1.gotomeeting.com/register/385144397
Doing more with less (Tools independant: this is the crazy sold out
STC webinar we did in late spring)
October 21 at 9am Pacific
Reserve your Webinar seat at:
https://www1.gotomeeting.com/register/865719205
$Id: guidelines.txt,v 1.20 2003/06/02 01:47:07 smith Exp $
xml-doc list guidelines
-------------------------------------------------------------------
These guidelines are sent as a Welcome message to new xml-doc
subscribers and once every four weeks to all current
subscribers. Please save these guidelines for later reference
and take a moment to review them now, including the PRIVACY
POLICY and NO-SPAM NOTICE at the end.
TABLE OF CONTENTS
-------------------------------------------------------------------
0. TOPIC GUIDELINES
1. ACCESSING THE XML-DOC WEB SITE
2. POSTING AND REPLYING TO MESSAGES
3. READING MESSAGES VIA THE WEB AND ACCESSING THE MESSAGE ARCHIVE
4. UNSUBSCRIBING, RECEIVING DIGESTS, AND PUTTING MAIL ON HOLD
5. DEALING WITH E-MAIL ATTACHMENTS
6. RECEIVING FURTHER HELP
A. PRIVACY POLICY
B. NO-SPAM NOTICE
C. NOTE ON TOPIC DRIFT, TROLLS, AND FLAMES
D. CHANGELOG
-------------------------------------------------------------------
0. TOPIC GUIDELINES
-----------------------------------------------------------------
xml-doc is for discussion of XML/SGML and document authoring,
particularly authoring of documentation for computer software
and hardware. Topics for which list members have a specific
interest include:
* XML editing applications
* Single-sourcing for multiple audiences/delivery formats
* XML-based content management systems
* DocBook and other document-oriented markup vocabularies
* Converting legacy documents
* Organizational strategies for structured authoring
* Document analysis and markup model design/refinement
* Transitioning from older (e.g. FrameMaker) environments
* Publishing (transforming and delivering XML content)
Please also take a moment to read the NOTE ON TOPIC DRIFT,
TROLLS, AND FLAMES at the end of this message.
1. ACCESSING THE XML-DOC WEB SITE
-----------------------------------------------------------------
As a member of the xml-doc mailing list, you also have access
to the xml-doc Web site:
http://groups.yahoo.com/group/xml-doc/
To use some features of the Web site, you also need to
choose a username and password and register with Yahoo Groups.
2. POSTING AND REPLYING TO MESSAGES
-----------------------------------------------------------------
To send a message to all the members of the mailing list,
e-mail it to:
xml-doc@yahoogroups.com
To post a message via the Web, visit:
http://groups.yahoo.com/post/xml-doc/
By default, when you reply to a message, the reply is sent to
all members of the list. If you want to reply just to the
author of a posted message, please specify only the author's
e-mail address in the "To:" field in your reply.
Here are a few general tips for posting and replying to
messages delivered to online mailing lists:
a. Use meaningful subject lines.
Try not to use generic, uninformative subject lines such as
"Easy question," "Help needed," "Urgent," and so on.
Instead, use meaningful subject lines that will quickly
make sense to the people whose help you are trying to get.
b. Quote only relevant parts of messages when replying.
When replying to a message, please don't quote the author's
entire message unless it's really necessary. Instead,
quote just the parts to which you are directly replying, or
quote only enough to establish a context for your reply.
c. Avoid idiomatic and colloquial English.
Be sensitive to the fact that a significant number of
subscribers to any English-language online mailing list are
non-native speakers of English. By avoiding idiomatic and
colloquial language, you ensure that your message will have
a higher degree of international readability.
Please also take a moment to read the NOTE ON TOPIC DRIFT,
TROLLS, AND FLAMES at the end of this message.
3. READING MESSAGES VIA THE WEB AND ACCESSING THE MESSAGE ARCHIVE
-----------------------------------------------------------------
All messages posted to the list are simultaneously posted to
xml-doc website and are immediately available at:
http://groups.yahoo.com/messages/xml-doc/
All messages are also automatically archived. To search
the archive, use the search box on the message page. To browse
the archive by month, visit the xml-doc main page:
http://groups.yahoo.com/group/xml-doc/
4. UNSUBSCRIBING, RECEIVING DIGESTS, AND PUTTING MAIL ON HOLD
-----------------------------------------------------------------
You can unsubscribe at any time by e-mailing a message to
xml-doc-unsubscribe@yahoogroups.com
To specify that you want to receive a digest of messages once
a day instead of receiving messages one at a time as they are
posted, send a blank e-mail message to:
xml-doc-digest@yahoogroups.com
To remain a list member, but receive no mail (for example, if
you plan to read messages by accessing the archive at the
xml-doc Web site or if you want to stop your xml-doc e-mail
while you are on a vacation), send a blank e-mail message to:
xml-doc-nomail@yahoogroups.com
To switch back from the "digest" or "no mail" settings to the
"normal" setting, send a blank e-mail message to:
xml-doc-normal@yahoogroups.com
You can also change your delivery settings from the xml-doc
Web site:
http://groups.yahoo.com/subscribe/xml-doc/
5. DEALING WITH E-MAIL ATTACHMENTS
-----------------------------------------------------------------
Any files that members attach to a message are stripped out
before the message is distributed to the list; you cannot send
or receive attachments via the list.
If you have a file you would like to make available to the
other members of the list, upload it directly to the file
sharing area of the xml-doc Web site:
http://groups.yahoo.com/files/xml-doc/
All interested members can then access or download the file at
their convenience.
6. RECEIVING FURTHER HELP
-----------------------------------------------------------------
If you have questions about the list itself and need to have
them answered by a real person, send them to:
xml-doc-owner@yahoogroups.com
Regards,
Michael Smith
xml-doc moderator and list owner
..................................................................
A. PRIVACY POLICY
-----------------------------------------------------------------
The xml-doc list moderator has a complete list of e-mail
addresses for all xml-doc subscribers, but will not provide
any subscriber e-mail addresses or personal information to any
third party, at any time, for any purpose. Yahoo Groups itself
has a separate privacy policy:
http://privacy.yahoo.com/
Read their policy carefully and make sure it is acceptable to
you. If it's not, you should unsubscribe from the list.
B. NO-SPAM NOTICE
-----------------------------------------------------------------
Please don't post messages to xml-doc that are not related
directly to XML/SGML and document authoring. Specific types of
messages that are inappropriate on the list include:
* Product or service announcements that have an excessive
amount of unobjective marketing hype
* Any "for sale" announcements; for example, if you have used
computer equipment or software you're trying to re-sell, or a
domain name you want to unload, posting an announcement to
xml-doc is not an appropriate way to try to find a buyer
You should also read the the Yahoo Terms of Service document,
which contains information about their policy toward spam, along
with other things.
http://docs.yahoo.com/info/terms/
C. NOTE ON TOPIC DRIFT, TROLLS, AND FLAMES
-----------------------------------------------------------------
Before posting or replying to a message, please remember this
list's stated purpose -- as outlined in the TOPIC GUIDELINES --
and show consideration for the fact that there are subscribers on
the list from a wide variety of professional backgrounds, and
that many people aren't going to be nearly as interested as you
might be in any particular discussion that drifts away from the
topic guidelines, no matter how important/relevant you may
personally believe the particular topic drift to be.
[0] http://www.catb.org/~esr/jargon/html/T/topic-drift.html
xml-doc is a relatively low-noise list, and relatively free
from trolls[1] and flames[2] and flame bait[3].
[1] http://www.catb.org/~esr/jargon/html/T/troll.html
[2] http://www.catb.org/~esr/jargon/html/F/flame.html
[3] http://www.catb.org/~esr/jargon/html/F/flame-bait.html
To help keep the noise level down, don't fan the flames, and
avoid feeding the trolls if/when they appear (a much better
strategy is simply to ignore them).
D. CHANGELOG
-----------------------------------------------------------------
2003-06-02 <smith@...>
* updated jargon-file URLs
2003-05-02 <smith@...>
* formatting tweak
* changed vim foldlevel
* minor reformatting
* formatting, minor updates
* topic drift, etc. section updated
2002-10-04 <smith@...>
* added section about topic drift, trolls, and flames (in another place)
* added section about topic drift, trolls, and flames
2002-07-02 <smith@...>
* changed 'DocBook and other DTDs' to 'DocBook and other markup
vocabularies'
* changed 'DTD creation' to 'markup model design'
2002-04-24 <smith@...>
* minor tweaks
* removed spam warnings
* expanded tabs
* added more no-spam warnings
* no-spam.txt: New file.
2002-04-03 <smith@...>
* fixed minor typo
2002-01-02 <smith@...>
* branches: 1.1.1; Initial revision
* added Id keyword
* New file.
// this file best viewed with Vim 6.1 or greater ;)
// vim:foldmethod=indent:foldlevel=1
XMLmind XMLmind is pleased to announce a new version of XMLmind XML Editor.
_____________________________________________
XMLmind XML Editor Personal Edition 4.1.0 can be downloaded from
http://www.xmlmind.com/xmleditor/download.shtml
Professional Edition users, please upgrade using this form:
http://www.xmlmind.com/store/download.php
(The above form is usually accessed through
http://www.xmlmind.com/xmleditor/upgrade.html.)
_____________________________________________
v4.1.0 (September 29, 2008)
Several very useful enhancements and a few bug fixes:
* FTPS (FTP over SSL) and SFTP (FTP over SSH)
support (Professional Edition only).
* Bookmarks.
* Multiple views of the same document are now
better synchronized in terms of visualizing
the selection.
More information in
http://www.xmlmind.com/xmleditor/changes.html
My problem in a nutshell: Deliver dynamic online help for a dynamic
platform.
Background
We produce software that allows people to create applications for a
variety of platforms (multiple interactive TV platforms, Blu-ray, etc).
Marketing has submitted a requirement that the documentation be
"platform-specific". That is, if a customer buys and installs a license
allowing them to develop applications for Blu-ray, only the
documentation applicable to Blu-ray is available.
No problem, right? Conditional text, generate the Blu-ray only
documentation, have a beer.
But, what if the customer licenses Blu-ray and, say, OpenTV? If I could
clone myself, I could just build a slew of different combinations of
help systems and let the installation engineer figure out which one to
install. But, I'm a lone writer (80%) and I don't have time for that.
And what about the situation where the customer licenses the Blu-ray
platform and then decides to become an iTV application developer?
My initial thinking is that we should provide the help in XML (DITA?),
tagging each platform-specific topic with the platform. But then what?
The help system would somehow need to be able to show/hide topics based
on the tag and license used to install the product.
Has anyone encountered (and solved) this problem? Can you point me in
the direction of help delivery systems that might be able to serve up
platform-specific help? Consultants that might help me with this
problem?
Oh, one other variable: I'm told that the next generation of the UI will
hide (not just stipple/disable) elements that are not available with
the existing license.
I'm currently using Framemaker (7) and WebWorks 2003 and looking to
migrate to a new tool (Frame 8 + Flare or RoboHelp or ePublisher Pro).
Thanks,
Hanna
[Non-text portions of this message have been removed]
Hi Hanna,
XML (DITA or DocBook) looks indeed a good option for your requirements.
The implementation will depend mostly on the format you deliver to your
readers. Options that come to mind:
- Automatically generate all possible combinations (if there's not too much)
- Dynamically hide content to reader by using specific CSS (and possibly
javascript)
- Dynamically generate the documentation at reading time through XSLT
(might be slow and overkill)
- Provide documentation as a set of independent modules for each
specific feature and show only relevant ones
Having some more information concerning the requirements:
- should non-relevant content be absolutely inaccessible to the users?
- is there a format (CHM, HTML, PDF, ...) and/or a reader (IE, FF) required?
- how many combinations can be imagined in total?
would help. There's probably no unique, magic solution anyway.
Depending on your schedule me and my colleagues might be available to
help you setup the system, should you go with XML.
Good luck :-)
Camille.
Hanna Nelson wrote:
>
> My problem in a nutshell: Deliver dynamic online help for a dynamic
> platform.
>
> Background
>
> We produce software that allows people to create applications for a
> variety of platforms (multiple interactive TV platforms, Blu-ray, etc).
> Marketing has submitted a requirement that the documentation be
> "platform-specific". That is, if a customer buys and installs a license
> allowing them to develop applications for Blu-ray, only the
> documentation applicable to Blu-ray is available.
>
> No problem, right? Conditional text, generate the Blu-ray only
> documentation, have a beer.
>
> But, what if the customer licenses Blu-ray and, say, OpenTV? If I could
> clone myself, I could just build a slew of different combinations of
> help systems and let the installation engineer figure out which one to
> install. But, I'm a lone writer (80%) and I don't have time for that.
> And what about the situation where the customer licenses the Blu-ray
> platform and then decides to become an iTV application developer?
>
> My initial thinking is that we should provide the help in XML (DITA?),
> tagging each platform-specific topic with the platform. But then what?
> The help system would somehow need to be able to show/hide topics based
> on the tag and license used to install the product.
>
> Has anyone encountered (and solved) this problem? Can you point me in
> the direction of help delivery systems that might be able to serve up
> platform-specific help? Consultants that might help me with this
> problem?
>
> Oh, one other variable: I'm told that the next generation of the UI will
> hide (not just stipple/disable) elements that are not available with
> the existing license.
>
> I'm currently using Framemaker (7) and WebWorks 2003 and looking to
> migrate to a new tool (Frame 8 + Flare or RoboHelp or ePublisher Pro).
>
> Thanks,
> Hanna
>
> [Non-text portions of this message have been removed]
>
>
[Non-text portions of this message have been removed]
It might have a strong learning curve, but the eclipse help framework
(which I believe can be essentially used as a stand along help browser)
can now use 'raw' DITA and present it as html. You'd have to work out
some mechanism to either only deliver the DITA files needed or to use an
additional (custom) eclipse plugin to hide or disable the topics that
weren't available. There maybe some commercial tools that cover
everything you need out-of-the-box, so maybe someone else on the list
can clue you in to one of them. The good news with the eclipse stuff is
if needed you should be able to hire a free lancer at reasonable rates
to do some custom code should you go that route.
Hanna Nelson wrote:
> My problem in a nutshell: Deliver dynamic online help for a dynamic
> platform.
>
> Background
>
> We produce software that allows people to create applications for a
> variety of platforms (multiple interactive TV platforms, Blu-ray, etc).
> Marketing has submitted a requirement that the documentation be
> "platform-specific". That is, if a customer buys and installs a license
> allowing them to develop applications for Blu-ray, only the
> documentation applicable to Blu-ray is available.
>
> No problem, right? Conditional text, generate the Blu-ray only
> documentation, have a beer.
>
> But, what if the customer licenses Blu-ray and, say, OpenTV? If I could
> clone myself, I could just build a slew of different combinations of
> help systems and let the installation engineer figure out which one to
> install. But, I'm a lone writer (80%) and I don't have time for that.
> And what about the situation where the customer licenses the Blu-ray
> platform and then decides to become an iTV application developer?
>
> My initial thinking is that we should provide the help in XML (DITA?),
> tagging each platform-specific topic with the platform. But then what?
> The help system would somehow need to be able to show/hide topics based
> on the tag and license used to install the product.
>
> Has anyone encountered (and solved) this problem? Can you point me in
> the direction of help delivery systems that might be able to serve up
> platform-specific help? Consultants that might help me with this
> problem?
>
> Oh, one other variable: I'm told that the next generation of the UI will
> hide (not just stipple/disable) elements that are not available with
> the existing license.
>
> I'm currently using Framemaker (7) and WebWorks 2003 and looking to
> migrate to a new tool (Frame 8 + Flare or RoboHelp or ePublisher Pro).
>
> Thanks,
> Hanna
>
--
Robert r. Sanders
Chief Technologist / CTO / COO
iPOV
(334) 821-5412
www.ipov.net
Hi there,
I'm not sure if Hanna is familiar with the Arbortext product suite but the
Arbortext "profiling" feature is exactly what is needed. It filters the
document down according to a definable set of criteria. In XML terms, the
applicability of certain XML elements (the criteria) are assigned using
attributes. The profiling tool then filters the content down to the relevant
set of elements before publishing to PDF, HTML, Help, etc.
I've attached a screenshot of the out-of-the-box Docbook XML sample.
I believe the XML editor by itself is $695. You can then add-on print or web
publishing features.
http://www.ptc.com/products/arbortext/editor/
Cheers,
Gareth
From: xml-doc@yahoogroups.com [mailto:xml-doc@yahoogroups.com] On Behalf Of
Robert R. Sanders
Sent: Tuesday, 14 October 2008 10:22 PM
To: xml-doc@yahoogroups.com
Subject: Re: [xml-doc] truly "dynamic" online help
It might have a strong learning curve, but the eclipse help framework
(which I believe can be essentially used as a stand along help browser)
can now use 'raw' DITA and present it as html. You'd have to work out
some mechanism to either only deliver the DITA files needed or to use an
additional (custom) eclipse plugin to hide or disable the topics that
weren't available. There maybe some commercial tools that cover
everything you need out-of-the-box, so maybe someone else on the list
can clue you in to one of them. The good news with the eclipse stuff is
if needed you should be able to hire a free lancer at reasonable rates
to do some custom code should you go that route.
Hanna Nelson wrote:
> My problem in a nutshell: Deliver dynamic online help for a dynamic
> platform.
>
> Background
>
> We produce software that allows people to create applications for a
> variety of platforms (multiple interactive TV platforms, Blu-ray, etc).
> Marketing has submitted a requirement that the documentation be
> "platform-specific". That is, if a customer buys and installs a license
> allowing them to develop applications for Blu-ray, only the
> documentation applicable to Blu-ray is available.
>
> No problem, right? Conditional text, generate the Blu-ray only
> documentation, have a beer.
>
> But, what if the customer licenses Blu-ray and, say, OpenTV? If I could
> clone myself, I could just build a slew of different combinations of
> help systems and let the installation engineer figure out which one to
> install. But, I'm a lone writer (80%) and I don't have time for that.
> And what about the situation where the customer licenses the Blu-ray
> platform and then decides to become an iTV application developer?
>
> My initial thinking is that we should provide the help in XML (DITA?),
> tagging each platform-specific topic with the platform. But then what?
> The help system would somehow need to be able to show/hide topics based
> on the tag and license used to install the product.
>
> Has anyone encountered (and solved) this problem? Can you point me in
> the direction of help delivery systems that might be able to serve up
> platform-specific help? Consultants that might help me with this
> problem?
>
> Oh, one other variable: I'm told that the next generation of the UI will
> hide (not just stipple/disable) elements that are not available with
> the existing license.
>
> I'm currently using Framemaker (7) and WebWorks 2003 and looking to
> migrate to a new tool (Frame 8 + Flare or RoboHelp or ePublisher Pro).
>
> Thanks,
> Hanna
>
--
Robert r. Sanders
Chief Technologist / CTO / COO
iPOV
(334) 821-5412
www.ipov.net
[Non-text portions of this message have been removed]
Hi Gareth -
Thanks for the info on Arbortext. I'm not familiar with it - I'll
check it out.
From what you said (filters the content down to the relevant set of
elements BEFORE publishing), it probably doesn't do what I need. I'm
looking for something that actually "publishes" on the fly
(republishing automatically if the installed software functionality
changes).
Thanks again,
Hanna
--- In xml-doc@yahoogroups.com, "Gareth Oakes" <lists@...> wrote:
>
> Hi there,
>
>
>
> I'm not sure if Hanna is familiar with the Arbortext product suite
but the
> Arbortext "profiling" feature is exactly what is needed. It filters the
> document down according to a definable set of criteria. In XML
terms, the
> applicability of certain XML elements (the criteria) are assigned using
> attributes. The profiling tool then filters the content down to the
relevant
> set of elements before publishing to PDF, HTML, Help, etc.
>
>
>
> I've attached a screenshot of the out-of-the-box Docbook XML sample.
>
>
>
> I believe the XML editor by itself is $695. You can then add-on
print or web
> publishing features.
>
>
>
> http://www.ptc.com/products/arbortext/editor/
>
>
>
> Cheers,
>
> Gareth
>
>
>
> From: xml-doc@yahoogroups.com [mailto:xml-doc@yahoogroups.com] On
Behalf Of
> Robert R. Sanders
> Sent: Tuesday, 14 October 2008 10:22 PM
> To: xml-doc@yahoogroups.com
> Subject: Re: [xml-doc] truly "dynamic" online help
>
>
>
> It might have a strong learning curve, but the eclipse help framework
> (which I believe can be essentially used as a stand along help browser)
> can now use 'raw' DITA and present it as html. You'd have to work out
> some mechanism to either only deliver the DITA files needed or to
use an
> additional (custom) eclipse plugin to hide or disable the topics that
> weren't available. There maybe some commercial tools that cover
> everything you need out-of-the-box, so maybe someone else on the list
> can clue you in to one of them. The good news with the eclipse stuff is
> if needed you should be able to hire a free lancer at reasonable rates
> to do some custom code should you go that route.
>
> Hanna Nelson wrote:
> > My problem in a nutshell: Deliver dynamic online help for a dynamic
> > platform.
> >
> > Background
> >
> > We produce software that allows people to create applications for a
> > variety of platforms (multiple interactive TV platforms, Blu-ray,
etc).
> > Marketing has submitted a requirement that the documentation be
> > "platform-specific". That is, if a customer buys and installs a
license
> > allowing them to develop applications for Blu-ray, only the
> > documentation applicable to Blu-ray is available.
> >
> > No problem, right? Conditional text, generate the Blu-ray only
> > documentation, have a beer.
> >
> > But, what if the customer licenses Blu-ray and, say, OpenTV? If I
could
> > clone myself, I could just build a slew of different combinations of
> > help systems and let the installation engineer figure out which one to
> > install. But, I'm a lone writer (80%) and I don't have time for that.
> > And what about the situation where the customer licenses the Blu-ray
> > platform and then decides to become an iTV application developer?
> >
> > My initial thinking is that we should provide the help in XML (DITA?),
> > tagging each platform-specific topic with the platform. But then
what?
> > The help system would somehow need to be able to show/hide topics
based
> > on the tag and license used to install the product.
> >
> > Has anyone encountered (and solved) this problem? Can you point me in
> > the direction of help delivery systems that might be able to serve up
> > platform-specific help? Consultants that might help me with this
> > problem?
> >
> > Oh, one other variable: I'm told that the next generation of the
UI will
> > hide (not just stipple/disable) elements that are not available with
> > the existing license.
> >
> > I'm currently using Framemaker (7) and WebWorks 2003 and looking to
> > migrate to a new tool (Frame 8 + Flare or RoboHelp or ePublisher Pro).
> >
> > Thanks,
> > Hanna
> >
> --
> Robert r. Sanders
> Chief Technologist / CTO / COO
> iPOV
> (334) 821-5412
> www.ipov.net
>
>
>
>
>
> [Non-text portions of this message have been removed]
>
Thanks for this idea.
I have actually produced Eclipse help plugins (using Webworks
Publisher 2003 + some custom tweaks), so it's not completely foreign
:-) As I recall, Eclipse help has a way to filter to just relevant
bits (not sure how granular it can be, though).
I saw an interesting presentation that included a help system that
allowed the user to filter the documentation themselves - presenting
all information, but making it easy to sort through just the relevant
info - building "books" on the fly (and output to PDF, if desired). I
didn't get an answer as to whether you could ship it with just the
relevant info displayed, but it seems like you could. Yet another
question for Marketing....
Hanna
--- In xml-doc@yahoogroups.com, "Robert R. Sanders"
<robert.sanders@...> wrote:
>
> It might have a strong learning curve, but the eclipse help framework
> (which I believe can be essentially used as a stand along help browser)
> can now use 'raw' DITA and present it as html. You'd have to work out
> some mechanism to either only deliver the DITA files needed or to
use an
> additional (custom) eclipse plugin to hide or disable the topics that
> weren't available. There maybe some commercial tools that cover
> everything you need out-of-the-box, so maybe someone else on the list
> can clue you in to one of them. The good news with the eclipse
stuff is
> if needed you should be able to hire a free lancer at reasonable rates
> to do some custom code should you go that route.
>
> Hanna Nelson wrote:
> > My problem in a nutshell: Deliver dynamic online help for a dynamic
> > platform.
> >
> > Background
> >
> > We produce software that allows people to create applications for a
> > variety of platforms (multiple interactive TV platforms, Blu-ray,
etc).
> > Marketing has submitted a requirement that the documentation be
> > "platform-specific". That is, if a customer buys and installs a
license
> > allowing them to develop applications for Blu-ray, only the
> > documentation applicable to Blu-ray is available.
> >
> > No problem, right? Conditional text, generate the Blu-ray only
> > documentation, have a beer.
> >
> > But, what if the customer licenses Blu-ray and, say, OpenTV? If I
could
> > clone myself, I could just build a slew of different combinations of
> > help systems and let the installation engineer figure out which one to
> > install. But, I'm a lone writer (80%) and I don't have time for
that.
> > And what about the situation where the customer licenses the Blu-ray
> > platform and then decides to become an iTV application developer?
> >
> > My initial thinking is that we should provide the help in XML (DITA?),
> > tagging each platform-specific topic with the platform. But then
what?
> > The help system would somehow need to be able to show/hide topics
based
> > on the tag and license used to install the product.
> >
> > Has anyone encountered (and solved) this problem? Can you point me in
> > the direction of help delivery systems that might be able to serve up
> > platform-specific help? Consultants that might help me with this
> > problem?
> >
> > Oh, one other variable: I'm told that the next generation of the
UI will
> > hide (not just stipple/disable) elements that are not available with
> > the existing license.
> >
> > I'm currently using Framemaker (7) and WebWorks 2003 and looking to
> > migrate to a new tool (Frame 8 + Flare or RoboHelp or ePublisher Pro).
> >
> > Thanks,
> > Hanna
> >
> --
> Robert r. Sanders
> Chief Technologist / CTO / COO
> iPOV
> (334) 821-5412
> www.ipov.net
>
Presentation takes place at DITA Europe 2008 on November 18th
Stilo International in conjunction with its customer STMicroelectronics,
is preparing to present a frank insight into the real-life challenges
and opportunities of adopting the new DITA (Darwin Information Typing
Architecture) standard for authoring, producing and delivering technical
information. At the upcoming DITA Europe 2008 conference, the two
companies will deliver a joint presentation that discloses their
experiences in an early European DITA publishing and content migration
project. STMicroelectronics is one of the world's largest
semiconductor manufacturers.
The presentation at DITA Europe 2008 will explain the strong business
case for DITA at STMicroelectronics and discuss the challenges faced by
the project team at key stages including:
* Managing the scope of the DITA project
* Communicating the benefits of DITA internally
* Creating style sheets that met requirements without being
over-complicated
* Migrating legacy content from FrameMaker
* Helping authors adjust to the new working practices
As a crucial part of the project, STMicroelectronics is piloting Stilo
Migrate, a brand new tool that simplifies the migration of legacy
documents to DITA and other XML publishing environments. Initially, the
solution allows users to upload Word and FrameMaker documents via the
Internet and provides a controlled document conversion workflow with
easy-to-follow steps. By using Stilo Migrate, organisations can both
reduce the time required for content migration and improve the accuracy
of the process.
To find out more about the DITA migration project at STMicroelectronics
and to read the entire article, click here
<http://www.stilo.com/NewsEvents/PressReleases/StiloSTtopresentatDITAEur\
ope2008/tabid/163/Default.aspx> .
You can see the joint presentation from Stilo and STMicroelectronics at
DITA Europe 2008, on Tuesday 18 November, 10.30am – 11.30am. Visit
www.infomanagementcenter.com/DITAeurope/index.htm
<http://www.infomanagementcenter.com/DITAeurope/index.htm> to register
and see the full conference programme.
Contact:
Helen Owens, Marketing Communications Manager
Stilo International plc
Tel: +44 (0) 1793 441444
howens@... <mailto:howens@...>
[Non-text portions of this message have been removed]
$Id: guidelines.txt,v 1.20 2003/06/02 01:47:07 smith Exp $
xml-doc list guidelines
-------------------------------------------------------------------
These guidelines are sent as a Welcome message to new xml-doc
subscribers and once every four weeks to all current
subscribers. Please save these guidelines for later reference
and take a moment to review them now, including the PRIVACY
POLICY and NO-SPAM NOTICE at the end.
TABLE OF CONTENTS
-------------------------------------------------------------------
0. TOPIC GUIDELINES
1. ACCESSING THE XML-DOC WEB SITE
2. POSTING AND REPLYING TO MESSAGES
3. READING MESSAGES VIA THE WEB AND ACCESSING THE MESSAGE ARCHIVE
4. UNSUBSCRIBING, RECEIVING DIGESTS, AND PUTTING MAIL ON HOLD
5. DEALING WITH E-MAIL ATTACHMENTS
6. RECEIVING FURTHER HELP
A. PRIVACY POLICY
B. NO-SPAM NOTICE
C. NOTE ON TOPIC DRIFT, TROLLS, AND FLAMES
D. CHANGELOG
-------------------------------------------------------------------
0. TOPIC GUIDELINES
-----------------------------------------------------------------
xml-doc is for discussion of XML/SGML and document authoring,
particularly authoring of documentation for computer software
and hardware. Topics for which list members have a specific
interest include:
* XML editing applications
* Single-sourcing for multiple audiences/delivery formats
* XML-based content management systems
* DocBook and other document-oriented markup vocabularies
* Converting legacy documents
* Organizational strategies for structured authoring
* Document analysis and markup model design/refinement
* Transitioning from older (e.g. FrameMaker) environments
* Publishing (transforming and delivering XML content)
Please also take a moment to read the NOTE ON TOPIC DRIFT,
TROLLS, AND FLAMES at the end of this message.
1. ACCESSING THE XML-DOC WEB SITE
-----------------------------------------------------------------
As a member of the xml-doc mailing list, you also have access
to the xml-doc Web site:
http://groups.yahoo.com/group/xml-doc/
To use some features of the Web site, you also need to
choose a username and password and register with Yahoo Groups.
2. POSTING AND REPLYING TO MESSAGES
-----------------------------------------------------------------
To send a message to all the members of the mailing list,
e-mail it to:
xml-doc@yahoogroups.com
To post a message via the Web, visit:
http://groups.yahoo.com/post/xml-doc/
By default, when you reply to a message, the reply is sent to
all members of the list. If you want to reply just to the
author of a posted message, please specify only the author's
e-mail address in the "To:" field in your reply.
Here are a few general tips for posting and replying to
messages delivered to online mailing lists:
a. Use meaningful subject lines.
Try not to use generic, uninformative subject lines such as
"Easy question," "Help needed," "Urgent," and so on.
Instead, use meaningful subject lines that will quickly
make sense to the people whose help you are trying to get.
b. Quote only relevant parts of messages when replying.
When replying to a message, please don't quote the author's
entire message unless it's really necessary. Instead,
quote just the parts to which you are directly replying, or
quote only enough to establish a context for your reply.
c. Avoid idiomatic and colloquial English.
Be sensitive to the fact that a significant number of
subscribers to any English-language online mailing list are
non-native speakers of English. By avoiding idiomatic and
colloquial language, you ensure that your message will have
a higher degree of international readability.
Please also take a moment to read the NOTE ON TOPIC DRIFT,
TROLLS, AND FLAMES at the end of this message.
3. READING MESSAGES VIA THE WEB AND ACCESSING THE MESSAGE ARCHIVE
-----------------------------------------------------------------
All messages posted to the list are simultaneously posted to
xml-doc website and are immediately available at:
http://groups.yahoo.com/messages/xml-doc/
All messages are also automatically archived. To search
the archive, use the search box on the message page. To browse
the archive by month, visit the xml-doc main page:
http://groups.yahoo.com/group/xml-doc/
4. UNSUBSCRIBING, RECEIVING DIGESTS, AND PUTTING MAIL ON HOLD
-----------------------------------------------------------------
You can unsubscribe at any time by e-mailing a message to
xml-doc-unsubscribe@yahoogroups.com
To specify that you want to receive a digest of messages once
a day instead of receiving messages one at a time as they are
posted, send a blank e-mail message to:
xml-doc-digest@yahoogroups.com
To remain a list member, but receive no mail (for example, if
you plan to read messages by accessing the archive at the
xml-doc Web site or if you want to stop your xml-doc e-mail
while you are on a vacation), send a blank e-mail message to:
xml-doc-nomail@yahoogroups.com
To switch back from the "digest" or "no mail" settings to the
"normal" setting, send a blank e-mail message to:
xml-doc-normal@yahoogroups.com
You can also change your delivery settings from the xml-doc
Web site:
http://groups.yahoo.com/subscribe/xml-doc/
5. DEALING WITH E-MAIL ATTACHMENTS
-----------------------------------------------------------------
Any files that members attach to a message are stripped out
before the message is distributed to the list; you cannot send
or receive attachments via the list.
If you have a file you would like to make available to the
other members of the list, upload it directly to the file
sharing area of the xml-doc Web site:
http://groups.yahoo.com/files/xml-doc/
All interested members can then access or download the file at
their convenience.
6. RECEIVING FURTHER HELP
-----------------------------------------------------------------
If you have questions about the list itself and need to have
them answered by a real person, send them to:
xml-doc-owner@yahoogroups.com
Regards,
Michael Smith
xml-doc moderator and list owner
..................................................................
A. PRIVACY POLICY
-----------------------------------------------------------------
The xml-doc list moderator has a complete list of e-mail
addresses for all xml-doc subscribers, but will not provide
any subscriber e-mail addresses or personal information to any
third party, at any time, for any purpose. Yahoo Groups itself
has a separate privacy policy:
http://privacy.yahoo.com/
Read their policy carefully and make sure it is acceptable to
you. If it's not, you should unsubscribe from the list.
B. NO-SPAM NOTICE
-----------------------------------------------------------------
Please don't post messages to xml-doc that are not related
directly to XML/SGML and document authoring. Specific types of
messages that are inappropriate on the list include:
* Product or service announcements that have an excessive
amount of unobjective marketing hype
* Any "for sale" announcements; for example, if you have used
computer equipment or software you're trying to re-sell, or a
domain name you want to unload, posting an announcement to
xml-doc is not an appropriate way to try to find a buyer
You should also read the the Yahoo Terms of Service document,
which contains information about their policy toward spam, along
with other things.
http://docs.yahoo.com/info/terms/
C. NOTE ON TOPIC DRIFT, TROLLS, AND FLAMES
-----------------------------------------------------------------
Before posting or replying to a message, please remember this
list's stated purpose -- as outlined in the TOPIC GUIDELINES --
and show consideration for the fact that there are subscribers on
the list from a wide variety of professional backgrounds, and
that many people aren't going to be nearly as interested as you
might be in any particular discussion that drifts away from the
topic guidelines, no matter how important/relevant you may
personally believe the particular topic drift to be.
[0] http://www.catb.org/~esr/jargon/html/T/topic-drift.html
xml-doc is a relatively low-noise list, and relatively free
from trolls[1] and flames[2] and flame bait[3].
[1] http://www.catb.org/~esr/jargon/html/T/troll.html
[2] http://www.catb.org/~esr/jargon/html/F/flame.html
[3] http://www.catb.org/~esr/jargon/html/F/flame-bait.html
To help keep the noise level down, don't fan the flames, and
avoid feeding the trolls if/when they appear (a much better
strategy is simply to ignore them).
D. CHANGELOG
-----------------------------------------------------------------
2003-06-02 <smith@...>
* updated jargon-file URLs
2003-05-02 <smith@...>
* formatting tweak
* changed vim foldlevel
* minor reformatting
* formatting, minor updates
* topic drift, etc. section updated
2002-10-04 <smith@...>
* added section about topic drift, trolls, and flames (in another place)
* added section about topic drift, trolls, and flames
2002-07-02 <smith@...>
* changed 'DocBook and other DTDs' to 'DocBook and other markup
vocabularies'
* changed 'DTD creation' to 'markup model design'
2002-04-24 <smith@...>
* minor tweaks
* removed spam warnings
* expanded tabs
* added more no-spam warnings
* no-spam.txt: New file.
2002-04-03 <smith@...>
* fixed minor typo
2002-01-02 <smith@...>
* branches: 1.1.1; Initial revision
* added Id keyword
* New file.
// this file best viewed with Vim 6.1 or greater ;)
// vim:foldmethod=indent:foldlevel=1
Hi all,
I am hoping you can help me with a question. I am trying to produce an
output that is ultimately going to be folded in half and read like a
booklet.
I can do the booklet part of the output in post processing in Adobe
Acrobat, however I need to make sure the front matter content and the
back matter content are the first and last pages of the entire PDF.
Therefore, I need to insert blank pages in the fo:page-layouts or
create new page layout fillers between the body flow content and the
backmatter content so that the final page count is mod 4.
I know I can display the total page count of the deliverable using
page-number-citation-last, but that only works if I send the FO
document through the FO processor to actually render that number into
the output. Is there a way to get that physical number or
count/label/mark/indicate each physical page to get the number in the
.fo result tree to use that information for post processing the
resulting .fo file copying the existing fo tree and inserting the
blank page sequences as needed?
Any help is greatly appreciated.
Thanks,
Jen
At 2008-11-20 05:05 +0000, Jennifer Linton wrote:
>I know I can display the total page count of the deliverable using
>page-number-citation-last, but that only works if I send the FO
>document through the FO processor to actually render that number into
>the output.
Right ... because each processor will process hyphenation,
justification, leading and other properties differently, the
resulting page count could be different with every processor. The
.fo file doesn't have page breaks or page counts, only the
abstractions that the FO engine replaces with actual page information
only after it determines what that information is by interpreting the
XSL-FO content.
>Is there a way to get that physical number or
>count/label/mark/indicate each physical page to get the number in the
>.fo result tree to use that information for post processing the
>resulting .fo file copying the existing fo tree and inserting the
>blank page sequences as needed?
Since the .fo tree only contains the abstractions of pointing to page
numbers after being processed, there is no way to inspect the .fo
tree for page breaks or for counting page numbers.
When shuffling pages for the various renditions of my XSL training
books, I also need to know how many blank pages to insert, and for
this I act on the resulting PDF file rather than the intermediate FO file.
I use the free iText library from sourceforge: http://itext.sf.net
It is a Java library, but I access it from Python using Jython:
http://www.jython.org
Then I get the basics of what I need:
from com.lowagie.text.pdf import PdfReader
reader = PdfReader( "file.pdf" )
totalPages = reader.getNumberOfPages()
Of course there is a lot more to iText, but that gives the flavour.
XSL engines have intermediate formats that include processed XSL-FO
information with page break information and page counts as
well. These files are XML instances which means you can manipulate
those with XSLT and not have to consider other programming languages.
I went the Python route because I use different XSL-FO tools at
different times and there is no consistency with the internal formats
(after all, they are internal). Plus, I can now shuffle PDF pages
regardless of how they are produced, such as merging my XSL-FO output
with the PDF pages output from OpenOffice.
I hope this helps.
. . . . . . . . . . . . . . Ken
--
Upcoming XSLT/XSL-FO, UBL and code list hands-on training classes:
: Sydney, AU 2009-01/02; Brussels, BE 2009-03; Prague, CZ 2009-03
Training tools: Comprehensive interactive XSLT/XPath 1.0/2.0 video
Video sample lesson: http://www.youtube.com/watch?v=PrNjJCh7Ppg
Video course overview: http://www.youtube.com/watch?v=VTiodiij6gE
G. Ken Holman mailto:gkholman@...
Crane Softwrights Ltd. http://www.CraneSoftwrights.com/x/
Male Cancer Awareness Nov'07 http://www.CraneSoftwrights.com/x/bc
Legal business disclaimers: http://www.CraneSoftwrights.com/legal
$Id: guidelines.txt,v 1.20 2003/06/02 01:47:07 smith Exp $
xml-doc list guidelines
-------------------------------------------------------------------
These guidelines are sent as a Welcome message to new xml-doc
subscribers and once every four weeks to all current
subscribers. Please save these guidelines for later reference
and take a moment to review them now, including the PRIVACY
POLICY and NO-SPAM NOTICE at the end.
TABLE OF CONTENTS
-------------------------------------------------------------------
0. TOPIC GUIDELINES
1. ACCESSING THE XML-DOC WEB SITE
2. POSTING AND REPLYING TO MESSAGES
3. READING MESSAGES VIA THE WEB AND ACCESSING THE MESSAGE ARCHIVE
4. UNSUBSCRIBING, RECEIVING DIGESTS, AND PUTTING MAIL ON HOLD
5. DEALING WITH E-MAIL ATTACHMENTS
6. RECEIVING FURTHER HELP
A. PRIVACY POLICY
B. NO-SPAM NOTICE
C. NOTE ON TOPIC DRIFT, TROLLS, AND FLAMES
D. CHANGELOG
-------------------------------------------------------------------
0. TOPIC GUIDELINES
-----------------------------------------------------------------
xml-doc is for discussion of XML/SGML and document authoring,
particularly authoring of documentation for computer software
and hardware. Topics for which list members have a specific
interest include:
* XML editing applications
* Single-sourcing for multiple audiences/delivery formats
* XML-based content management systems
* DocBook and other document-oriented markup vocabularies
* Converting legacy documents
* Organizational strategies for structured authoring
* Document analysis and markup model design/refinement
* Transitioning from older (e.g. FrameMaker) environments
* Publishing (transforming and delivering XML content)
Please also take a moment to read the NOTE ON TOPIC DRIFT,
TROLLS, AND FLAMES at the end of this message.
1. ACCESSING THE XML-DOC WEB SITE
-----------------------------------------------------------------
As a member of the xml-doc mailing list, you also have access
to the xml-doc Web site:
http://groups.yahoo.com/group/xml-doc/
To use some features of the Web site, you also need to
choose a username and password and register with Yahoo Groups.
2. POSTING AND REPLYING TO MESSAGES
-----------------------------------------------------------------
To send a message to all the members of the mailing list,
e-mail it to:
xml-doc@yahoogroups.com
To post a message via the Web, visit:
http://groups.yahoo.com/post/xml-doc/
By default, when you reply to a message, the reply is sent to
all members of the list. If you want to reply just to the
author of a posted message, please specify only the author's
e-mail address in the "To:" field in your reply.
Here are a few general tips for posting and replying to
messages delivered to online mailing lists:
a. Use meaningful subject lines.
Try not to use generic, uninformative subject lines such as
"Easy question," "Help needed," "Urgent," and so on.
Instead, use meaningful subject lines that will quickly
make sense to the people whose help you are trying to get.
b. Quote only relevant parts of messages when replying.
When replying to a message, please don't quote the author's
entire message unless it's really necessary. Instead,
quote just the parts to which you are directly replying, or
quote only enough to establish a context for your reply.
c. Avoid idiomatic and colloquial English.
Be sensitive to the fact that a significant number of
subscribers to any English-language online mailing list are
non-native speakers of English. By avoiding idiomatic and
colloquial language, you ensure that your message will have
a higher degree of international readability.
Please also take a moment to read the NOTE ON TOPIC DRIFT,
TROLLS, AND FLAMES at the end of this message.
3. READING MESSAGES VIA THE WEB AND ACCESSING THE MESSAGE ARCHIVE
-----------------------------------------------------------------
All messages posted to the list are simultaneously posted to
xml-doc website and are immediately available at:
http://groups.yahoo.com/messages/xml-doc/
All messages are also automatically archived. To search
the archive, use the search box on the message page. To browse
the archive by month, visit the xml-doc main page:
http://groups.yahoo.com/group/xml-doc/
4. UNSUBSCRIBING, RECEIVING DIGESTS, AND PUTTING MAIL ON HOLD
-----------------------------------------------------------------
You can unsubscribe at any time by e-mailing a message to
xml-doc-unsubscribe@yahoogroups.com
To specify that you want to receive a digest of messages once
a day instead of receiving messages one at a time as they are
posted, send a blank e-mail message to:
xml-doc-digest@yahoogroups.com
To remain a list member, but receive no mail (for example, if
you plan to read messages by accessing the archive at the
xml-doc Web site or if you want to stop your xml-doc e-mail
while you are on a vacation), send a blank e-mail message to:
xml-doc-nomail@yahoogroups.com
To switch back from the "digest" or "no mail" settings to the
"normal" setting, send a blank e-mail message to:
xml-doc-normal@yahoogroups.com
You can also change your delivery settings from the xml-doc
Web site:
http://groups.yahoo.com/subscribe/xml-doc/
5. DEALING WITH E-MAIL ATTACHMENTS
-----------------------------------------------------------------
Any files that members attach to a message are stripped out
before the message is distributed to the list; you cannot send
or receive attachments via the list.
If you have a file you would like to make available to the
other members of the list, upload it directly to the file
sharing area of the xml-doc Web site:
http://groups.yahoo.com/files/xml-doc/
All interested members can then access or download the file at
their convenience.
6. RECEIVING FURTHER HELP
-----------------------------------------------------------------
If you have questions about the list itself and need to have
them answered by a real person, send them to:
xml-doc-owner@yahoogroups.com
Regards,
Michael Smith
xml-doc moderator and list owner
..................................................................
A. PRIVACY POLICY
-----------------------------------------------------------------
The xml-doc list moderator has a complete list of e-mail
addresses for all xml-doc subscribers, but will not provide
any subscriber e-mail addresses or personal information to any
third party, at any time, for any purpose. Yahoo Groups itself
has a separate privacy policy:
http://privacy.yahoo.com/
Read their policy carefully and make sure it is acceptable to
you. If it's not, you should unsubscribe from the list.
B. NO-SPAM NOTICE
-----------------------------------------------------------------
Please don't post messages to xml-doc that are not related
directly to XML/SGML and document authoring. Specific types of
messages that are inappropriate on the list include:
* Product or service announcements that have an excessive
amount of unobjective marketing hype
* Any "for sale" announcements; for example, if you have used
computer equipment or software you're trying to re-sell, or a
domain name you want to unload, posting an announcement to
xml-doc is not an appropriate way to try to find a buyer
You should also read the the Yahoo Terms of Service document,
which contains information about their policy toward spam, along
with other things.
http://docs.yahoo.com/info/terms/
C. NOTE ON TOPIC DRIFT, TROLLS, AND FLAMES
-----------------------------------------------------------------
Before posting or replying to a message, please remember this
list's stated purpose -- as outlined in the TOPIC GUIDELINES --
and show consideration for the fact that there are subscribers on
the list from a wide variety of professional backgrounds, and
that many people aren't going to be nearly as interested as you
might be in any particular discussion that drifts away from the
topic guidelines, no matter how important/relevant you may
personally believe the particular topic drift to be.
[0] http://www.catb.org/~esr/jargon/html/T/topic-drift.html
xml-doc is a relatively low-noise list, and relatively free
from trolls[1] and flames[2] and flame bait[3].
[1] http://www.catb.org/~esr/jargon/html/T/troll.html
[2] http://www.catb.org/~esr/jargon/html/F/flame.html
[3] http://www.catb.org/~esr/jargon/html/F/flame-bait.html
To help keep the noise level down, don't fan the flames, and
avoid feeding the trolls if/when they appear (a much better
strategy is simply to ignore them).
D. CHANGELOG
-----------------------------------------------------------------
2003-06-02 <smith@...>
* updated jargon-file URLs
2003-05-02 <smith@...>
* formatting tweak
* changed vim foldlevel
* minor reformatting
* formatting, minor updates
* topic drift, etc. section updated
2002-10-04 <smith@...>
* added section about topic drift, trolls, and flames (in another place)
* added section about topic drift, trolls, and flames
2002-07-02 <smith@...>
* changed 'DocBook and other DTDs' to 'DocBook and other markup
vocabularies'
* changed 'DTD creation' to 'markup model design'
2002-04-24 <smith@...>
* minor tweaks
* removed spam warnings
* expanded tabs
* added more no-spam warnings
* no-spam.txt: New file.
2002-04-03 <smith@...>
* fixed minor typo
2002-01-02 <smith@...>
* branches: 1.1.1; Initial revision
* added Id keyword
* New file.
// this file best viewed with Vim 6.1 or greater ;)
// vim:foldmethod=indent:foldlevel=1
Hello all. I have permission from this list's moderator to post the
following:
I am a graduate student at the University of Minnesota, Twin Cities.
As part of my master’s degree in scientific and technical
communication (MS-STC program), I am taking a Research Methods class
and the final project is a research project.
I have chosen to conduct a brief study about current implementations
of single sourcing and structured authoring. I am interested in this
topic because I have worked as a technical writer for almost 12 years
and the company I currently work for is beginning to implement
structured authoring. I am curious about how other companies have
converted to this different process and if the conversion has resulted
in better documentation.
If you can take a few minutes from your busy schedule and answer these
questions for me, I would appreciate it. If I am unable to find
participants for this survey, I will have to make up answers and I
have to admit, I am uncomfortable with that idea, even if it is just
for a class assignment. Even if you have no experience with single
sourcing or structured authoring, I would appreciate your opinions, too.
Please send your answers directly back to: Susan Schnelbach at schne637@...
but if you accidentally send the answers to the entire group, I'll
still get them. And thanks.
1. What is your job title?
2. What is your job description?
3. What is your gender? _______M ________F
4. What is your highest level of education?
High school
Some college
Certificate program (college level)
Associate’s degree
Bachelor’s degree
Master’s degree
PhD
Other:_________
5. If you have a college degree, what field is your degree in:
__________________________
6. How long have you been a technical writer or information designer?
7. How many technical writers are at your company?
8. How many technical writers produce the same content that you
produce or could reuse your content?
9. If you use a word processor for authoring, do you reuse content via
a. Cut and paste?
b. Master and subdocuments?
c. Library files or snippets?
d. Other__________
Single Sourcing
10. Do you use a formal single-sourcing process? If no, skip to 19.
11. If yes, how long have you been using single-sourcing or structured
authoring techniques to create content?
12. If you do use a formal single-sourcing process, has adopting
single-sourcing increased your output?
13. What level of granularity do you use? (Select all that apply)
a. chapter
b. section
c. paragraph
d. topic
e. sentence
f. other:
14. What percentage of your documentation do you build from reusable
content?
15. Do you also create non-single-sourced or non-structured authoring
end user documents?
16. Do you reuse content written by other writers?
17. Do other writers reuse your content?
18. Are you responsible for creating sections of the final product or
the complete final product?
Structured Authoring
19. Do you use a structured authoring process? If no, skip to question
26.
20. Which structured authoring architecture do you use?
a. DITA
b. DocBook
c. Other:
21. If yes, what type of documentation do you produce?
a. End-user documentation
b. Internal documentation
c. Compliance or certification documentation
d. Other:
22. Have you eliminated all transition text from your topics to ensure
reusability?
23. Do you feel that you have any creative control over content
production?
24. Do you feel that structured authoring has made your job more like
an assembly line?
25. Has your audience complained about the usability of your documents?
Other
26. Please give as brief or as detailed a description about your
technical writing process as you would like to share, focusing on how
you do or do not reuse existing content.
Thank you very much for completing this survey. These results are for
a graduate-level class and will not be used for purpose other than for
my final project for the class. No names or identities will be
released in the report.
Please send your answers directly back to: Susan Schnelbach at schne637@...
.
[Non-text portions of this message have been removed]
Montréal in August has always been the place and time
for serious markup geeks to meet. "Balisage 2009" and
the "International Symposium on Processing XML
Efficiently" continue the tradition.
Balisage is a peer reviewed conference designed to meet the needs of
markup theoreticians and practitioners who are pushing the boundaries of
the field. It's all about the markup: how to create it; what it means;
hierarchies and overlap; modeling; taxonomies; transformation; query,
searching, and retrieval; presentation and accessibility; making systems
that make markup dance (or dance faster to a different tune in a smaller
space) - in short, changing the world and the web through the power of
marked-up information.
When:
August 11 - 14, 2009 Balisage: The Markup Conference 2009
August 10, 2009 - International Symposium on Processing XML Efficiently
Where:
Montréal, Canada
To Participate:
We welcome papers about topic maps, document modeling, markup of
overlapping structures, ontologies, metadata, content management, and
other markup-related topics at Balisage. If you want to talk, in detail
XML, XSL, SGML, LMNL, XSL-FO, XTM, RDF, XQuery, Topic Maps, SVG, MathML
OWL, UBL, XSD, TexMECS, RNG, or any other markup-related topic, we urge
you to participate in Balisage.
How:
Submit full papers in XML to info@...
Guidelines, DTDs, schemas, and details at
http://www.balisage.net/submissions.html
Schedule:
15 March 2009 - Peer Review Applications Due
24 April 2009 - Paper Submissions Due
22 May 2009 - Speakers Notified
17 July 2009 - Revised Papers Due
10 August 2009 - Processing Symposium
11-14 August 2009 - Balisage: The Markup Conference
If you have any questions about Balisage send email to mailto:info@...
--
======================================================================
B. Tommie Usdin mailto:btusdin@...
Mulberry Technologies, Inc. http://www.mulberrytech.com
17 West Jefferson Street Phone: 301/315-9631
Suite 207 Direct Line: 301/315-9634
Rockville, MD 20850 Fax: 301/315-8285
----------------------------------------------------------------------
Mulberry Technologies: A Consultancy Specializing in XML and SGML
======================================================================
XMLmind is happy to announce the version 2.2
of Qizx and Qizx/open.
Qizx Free Engine can be downloaded from
http://www.xmlmind.com/qizx/download.shtml
Qizx/open can be downloaded from
http://www.xmlmind.com/qizx/qizxopen.shtml
Qizx customers, please upgrade using this form:
http://www.xmlmind.com/store/download.php
(The above form is usually accessed through
http://www.xmlmind.com/qizx/upgrade.html.)
---------------------------------------------
Qizx is an embeddable, high-speed, native XML
indexing and query engine written in Java(TM),
with the querying and processing capabilities of a
fully fledged XML Query implementation.
New features in version 2.2:
* Support of XQuery 1.1 features: "group by" and
"for ... window" clauses in FLWOR expressions.
* New liberal licensing scheme: Server, Site and
Developer licenses.
The full source code can now be purchased.
Please visit http://www.xmlmind.com/qizx/changes.html
for more information.
Qizx is available in several editions:
* The commercial product has 3 liberal licenses
both for corporate application development, and
for royalty-free distributable products.
* The Free Engine edition is a fully functional
version of Qizx which can be used for developing
or in production. It is limited in database
size (one gigabyte of XML approximately).
* Qizx/open is an open-source version of the XML
Query interpreter of Qizx. Qizx/open has been
available since 2003 and is recognized as one of
the fastest and most advanced XML Query
implementations.
Please visit http://www.xmlmind.com/qizx/ for more
information about Qizx.
CALL FOR PARTICIPATION
International Symposium on Processing XML Efficiently:
Overcoming Limits on Space, Time, or Bandwidth
Monday August 10, 2009
Hotel Europa, Montréal, Canada
Chair: Michael Kay, Saxonica
Details: http://www.balisage.net/Processing/
Developers have said it: "XML is too slow!", where "slow" can mean many
things including elapsed time, throughput, latency, memory use, and
bandwidth consumption. The aim of this one-day symposium is to understand
these problems better and to explore and share approaches to solving them.
Topics
Proposals for presentations at the Processing Symposium may address any
aspect of processing XML efficiently. We welcome:
* Theoretical discussions
* Practical experience and case studies
* Product talks (if clearly identified as such)
* Discussions of:
- software design to facilitate processing
- document design to facilitate processing
- management of XML applications in a processing-intensive environment
- measuring efficiency of XML processing
* and related topics and approaches.
Submission Instructions
Submissions are due on or before April 24, 2009. To submit a proposal to
the Processing XML Symposium send email to info@..., including:
1. Your name, email, affiliation, and telephone number
2. Title of your presentation
3. Short description of your topic (150 words)
4. Detailed description of your topic and presentation. (It would be a
convenience to the organizers of symposium submissions were in XML
according to the guidelines and model for Balisage submissions, but
this is not required.)
5. Biographical information on all authors
6. Any other information you think will help the conference committee
evaluate your proposed presentation
Hyde Park Speaker's Corner
During the day, Symposium attendees may submit mini-proposals for five
minute time-slots; these five-minute presentations will be given during
the "Hyde Park Speaker's Corner" session in the afternoon. Speakers will
be encouraged to divide their five minutes into two parts: three minutes
during which they may state opinions, preferences, or experiences relating
to processing XML efficiently, and two minutes during which the other
attendees may react. If there are more proposals than can be accommodated
proposals from people who have not already spoken will be preferred, and
random selections from the remaining proposals will be made. As at the
"Speaker's Corner" in London's Hyde Park, there will be virtually no
restrictions on allowed content. However, the Symposium's organizers
will terminate presentations that are not clearly related to the symposium
topic, that are disrespectful of others or their points of view, or that are
still incomplete after five minutes have elapsed.
There is nothing so practical as a good theory
--
======================================================================
Balisage: The Markup Conference 2009 mailto:info@...
August 11-14, 2009 http://www.balisage.net
Processing XML Efficiently: August 10, 2009 Montreal, Canada
======================================================================
Hi Group,
I am new to this group (and xml), trying to evaluate XML solutions for
generating our man
pages. I have looked into both DocBook and DITA.
We currently deliver a printed FrameMaker command reference manual that includes
printed versions of all the man pages available on the system with the man
utility. I create
the man pages source in ClearCase using nroff markup, and then I paste the text
into he
FrameMaker manual. This process is tedious and error prone, and it is virtually
impossible
to keep he two sets of documents in perfect sync over time. As a matter of fact,
when i
took over this project, discrepancies between the source and the printed doc
were
rampant and a source off customer complaints.
I am looking to generate both the nroff and the FrameMaker manual from a single
source.
I have looked into DocBook and DITA, none of which work out of the box, and will
require
customization to make the solution work.
Docbook's refentry seems to be better suited for our content requirements (man
page
format), but my understanding is that FrameMaker support for docbook is less
than
optimal. In addition, I was unable to make docbook work on Windows (via cygwin),
and
basically gave up.
The DITA tools work like a charm and generate decent xhtml output for man pages
out of
the box, but the troff transform is under-developed and apparently not used by
many
people, if any. It is basically a text dump, and doesn't even generate the man
page header
(.TH <cmd> <date> <product>) necessary to display the page.
I am developing a "proof-of-concept" demo to convince management to invest in a
single
sourcing solution, and am having a hard time deciding which way to go (DocBook
or
DITA). It's one thing to generate a quick_and_dirty_little demo to win over the
sceptics.
It's another thing to go down a certain path for arbitrary reasons (e.g.,
inability to get
Docbook to work on Windows).
I am curious how other people generate man pages and associated command
reference
manuals, and whether there is an industry standard for single sourcing these?
Given the popularity of DITA, why has there been not more interest n developing
the nroff
transform to support at least a workable man page output.
Looking forward to your input.
eva
----
Technical Writer
Brocade Communications
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
"eknodt" <eknodt@...> writes:
> In addition, I
> was unable to make docbook work on Windows (via cygwin), and basically
> gave up.
Eva,
I think I once got the cygwin DocBook tool chain to work all the way
- From xml to pdf, but I then forgot what I did, and I was never able to
recreate it.
At some point, I discovered eDE
(<http://www.e-novative.info/software/ede.php>), and it was the easiest
tool chain I've seen outside of Linux (where I now exist).
I saw one amusing problem with eDE, and I think it had to do with
generating PDFs. I would generate the output, and the system would say
it succeeded, but the output file was not to be found. After a bit of
exploration, I discovered that it was a spaces-in-file-names problem.
Unlike most of those, though, this was truly creative. eDE created a
new directory tree called
C:\Documents%20and%20Settings\My%20Name\... and stuffed the file there.
The "%20" strings aren't encodings of spaces; they are characters in the
revised path name! IOW, I now had both C:\Documents and Settings and
C:\Documents%20and%20Settings.
At least the last time I used it, xIncludes were not part of eDE out of
the box, but someone had posted how he had added them in on their forum.
If you try eDE, it's easiest to use it exactly as they suggest, at least
at first. Once you figure out how and where it generates xml file
templates, you can begin to think of creating your own files from
scratch if you want. As I recall, if the files and directory structures
aren't created the way it expects, its conversions will fail.
Bill
- --
Bill Harris http://facilitatedsystems.com/weblog/
Facilitated Systems Everett, WA 98208 USA
http://facilitatedsystems.com/ phone: +1 425 337-5541
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
iEYEARECAAYFAklGED8ACgkQ3J3HaQTDvd/NBQCdHNeXBizZQYrKPfFxuskyTO5P
0pcAnimYz7wfWeEWfUnnrFvfyVDvbGPR
=58BB
-----END PGP SIGNATURE-----
eknodt <eknodt@...>, 2008-12-14 20:25 -0000:
> I am new to this group (and xml), trying to evaluate XML solutions for
generating our man
> pages. I have looked into both DocBook and DITA.
> [...]
> I am looking to generate both the nroff and the FrameMaker manual from a
single source.
> I have looked into DocBook and DITA, none of which work out of the box, and
will require
> customization to make the solution work.
>
> Docbook's refentry seems to be better suited for our content requirements (man
page
> format),
The DocBook XSL stylesheets have support for generating
high-quality, full-featured nroff man-page output from DocBook
refentry source. (I know because I'm the maintainer for the
DocBook manpages backend, and the one who added a good number of
the features to it...)
It supports, tables (including complex tables with cells spanning
rows and columns), translates hyperlinks and footnotes into
something useful in text-only man pages, handles deeply-nested
lists, translates Unicode characters correctly, and a number of
other pretty useful things. It basically aims to take anything you
want to throw at it that's valid in a DocBook refentry, and
produce genuine, nroff/groff man-page output that preserves all of
your content and present in as usable form as it can, within the
limitations of the format.
> but my understanding is that FrameMaker support for docbook is less than
> optimal.
The problem of relatively poor off-the-shelf support for DocBook
in Framemaker is unfortunately something that nobody except the
vendor of that product can do much about.
> In addition, I was unable to make docbook work on Windows (via cygwin), and
> basically gave up.
There are a lot of people using DocBook under Windows and Cygwin.
If you've run into specific problems, you might be able to get
help with them by posting questions to the docbook-apps mailing
list.
That said, rather than using Cygwin, you'd probably be better off
getting a modern Ubuntu or other Linux environment set up. These
days, using virtualization software like VMWare or Parallels,
that's a pretty cheap and straightforward and painless thing to
get set up (you can have one PC/laptop that has Mac OSX, Linux,
and Windows on the same machine).
--Mike
--
Michael(tm) Smith
http://people.w3.org/mike/
> We currently deliver a printed FrameMaker command reference
> manual that includes printed versions of all the man pages
> available on the system with the man utility. I create
> the man pages source in ClearCase using nroff markup, and
> then I paste the text into he FrameMaker manual. [...]
>
> I am looking to generate both the nroff and the FrameMaker
> manual from a single source. I have looked into DocBook and
> DITA, none of which work out of the box [...]
>
> Docbook's refentry seems to be better suited for our
> content requirements (man page format), but my understanding
> is that FrameMaker support for docbook is less than
> optimal. [...]
>
> The DITA tools work like a charm and generate decent xhtml
> output for man pages out of the box, but the troff transform
> is under-developed and apparently not used by many people,
> if any.
A quick & dirty approach, that would nonetheless produce
decent results, would be to use groff to format the man pages
as PDFs. You could break up multi-page PDFs after the fact, or
use a script to generate each page individually. Include each
PDF'ed page into your manual, using a master page that makes
as much room as possible for the man page. Using groff 1.19.x,
you can redefine the .PT and .BT macros to make the headers &
footers match the rest of the manual, and there's some flexi-
bility with regard to paper sizes. This approach has the added
advantage of minimally impacting the rest of your setup.
If you have other reasons for adopting *ML for your docs, I
would recommend making DocBook work simply because it's more
suited for generating man pages -- Michael's work on *roff
output for DocBook looks pretty good. You can use doclifter
<http://www.catb.org/~esr/doclifter/> to convert your man
pages to DocBook; you'll have to do some cleanup but ESR
claims that it will do up to 95% of the work. But from my
own experience, you either need to grow or hire an *ML expert
to get and keep your tool chain in working order.
-- Larry
eknodt wrote:
>
> I am new to this group (and xml), trying to evaluate XML solutions for
generating our man
> pages. I have looked into both DocBook and DITA.
> ....
> The DITA tools work like a charm and generate decent xhtml output for man
pages out of
> the box, but the troff transform is under-developed and apparently not used by
many
> people, if any. It is basically a text dump, and doesn't even generate the
man page header
> (.TH <cmd> <date> <product>) necessary to display the page.
>
Interesting message, Eva. As it happens, my group is going down
a similar path. We're pretty committed to DITA at this point, so
that's the avenue I'll be investigating.
My initial thoughts were to create a specialization of .ditamap,
or else use a "container topic" (just heard about them, need to
investigate). But from what you say, the troff generation will
be the harder part.
We do have something working along those lines, though. I wrote an
HTML to troff converter that works pretty well, as long as the
HTML source is limited to the man page format. (Ruby program)
There is one significant problem with that tool, though. It uses
the troff "table macro" processor, and that processor is just
horrible. It makes super wide columns for things that have little
text, and vice versa, and it has no respect whatever for an 80-column
limit.
There is a possible solution for that, as well. My first ever
coding experience in Java was a program to reformat HTML tables
for display on old, 80-character ASCII terminals in the DMV, or
some such government office. Over the course of a month, it grew
to encompass row and column spanning, and it implemented a weighting
heuristic for column sizing. That code is sitting in a box,
somewhere, on an old diskette. If I were to find it, I'm sure it
would do a better job than the man table macro processor is
currently doing.
Of course, finding time for such stuff is the hard part...
--
Eric Armstrong, Document Systems Architect, Sun Microsystems
http://blogs.sun.com/coolstuffhttp://www.artima.com/weblogs/index.jsp?blogger=cooltools
Thanks everyone for your great suggestions.
I will definitely give docbook another look.
Cheers,
eva
--- In xml-doc@yahoogroups.com, "Michael(tm) Smith" <smith@...> wrote:
>
> eknodt <eknodt@...>, 2008-12-14 20:25 -0000:
>
> > I am new to this group (and xml), trying to evaluate XML solutions for
generating our
man
> > pages. I have looked into both DocBook and DITA.
> > [...]
> > I am looking to generate both the nroff and the FrameMaker manual from a
single
source.
> > I have looked into DocBook and DITA, none of which work out of the box, and
will
require
> > customization to make the solution work.
> >
> > Docbook's refentry seems to be better suited for our content requirements
(man page
> > format),
>
> The DocBook XSL stylesheets have support for generating
> high-quality, full-featured nroff man-page output from DocBook
> refentry source. (I know because I'm the maintainer for the
> DocBook manpages backend, and the one who added a good number of
> the features to it...)
>
> It supports, tables (including complex tables with cells spanning
> rows and columns), translates hyperlinks and footnotes into
> something useful in text-only man pages, handles deeply-nested
> lists, translates Unicode characters correctly, and a number of
> other pretty useful things. It basically aims to take anything you
> want to throw at it that's valid in a DocBook refentry, and
> produce genuine, nroff/groff man-page output that preserves all of
> your content and present in as usable form as it can, within the
> limitations of the format.
>
> > but my understanding is that FrameMaker support for docbook is less than
> > optimal.
>
> The problem of relatively poor off-the-shelf support for DocBook
> in Framemaker is unfortunately something that nobody except the
> vendor of that product can do much about.
>
> > In addition, I was unable to make docbook work on Windows (via cygwin), and
> > basically gave up.
>
> There are a lot of people using DocBook under Windows and Cygwin.
> If you've run into specific problems, you might be able to get
> help with them by posting questions to the docbook-apps mailing
> list.
>
> That said, rather than using Cygwin, you'd probably be better off
> getting a modern Ubuntu or other Linux environment set up. These
> days, using virtualization software like VMWare or Parallels,
> that's a pretty cheap and straightforward and painless thing to
> get set up (you can have one PC/laptop that has Mac OSX, Linux,
> and Windows on the same machine).
>
> --Mike
>
> --
> Michael(tm) Smith
> http://people.w3.org/mike/
>
Bill Harris wrote:
> At some point, I discovered eDE
> (<http://www.e-novative.info/software/ede.php>), and it was the easiest
> tool chain I've seen outside of Linux (where I now exist).
>
This interface is truly amazing. Takes exactly 2 minutes to set up.
Just what i was looking for.
This now provides me with the opportunity to truly compare DITA and
Docbook in relation to our requirements and see for myself.
Thank you so much for calling my attention to this tool!
best,
eva
(cross posted)
Now seeking speakers for two conferences coming in 2009.
The RealWorld DITA 2009 Conference
September 14-16, 2009
Raleigh, North Carolina USA
http://www.aboveandbeyondlearning.com/ditaconference.html
The Summer XML 2009 Conference
July 27-28, 2009
Raleigh, North Carolina USA
http://www.aboveandbeyondlearning.com/xmlconference.html
The Summer XML is a restart of the old "Tri-XML" conferences.
Are you interested in presenting at either? If so, please email your topic
ideas directly to mailto:kaywhatley@... . In
addition to the topics listed on the conferences website, we are interested
in presentations on social media and future tech.
+ + + + + + + +
Kay Whatley
Conference Producer/Production Manager
Above and Beyond Learning Corp.
+ + + + + + + +
I don't see it mentioning troff.
Wasn't that an important solution criteria?
eknodt wrote:
> Bill Harris wrote:
>
>> At some point, I discovered eDE
>> (<http://www.e-novative.info/software/ede.php>), and it was the easiest
>> tool chain I've seen outside of Linux (where I now exist).
>>
> This interface is truly amazing. Takes exactly 2 minutes to set up.
> Just what i was looking for.
>
> This now provides me with the opportunity to truly compare DITA and
> Docbook in relation to our requirements and see for myself.
>
> Thank you so much for calling my attention to this tool!
>
> best,
>
> eva
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
--
Eric Armstrong, Document Systems Architect, Sun Microsystems
http://blogs.sun.com/coolstuffhttp://www.artima.com/weblogs/index.jsp?blogger=cooltools
Send Email
