Flow Write

What is API Documentation

noreply@blogger.com (LISHA LI) — Mon, 23 Feb 2015 19:24:00 +0000

I really like this blog posting for the STC Puget Sound chapter that explains what API documentation is all about. Click to read

Single-sourcing strategy I used for a Developer Guide

noreply@blogger.com (LISHA LI) — Fri, 01 Aug 2014 17:21:00 +0000

I utilized single-sourcing for most of my documentation projects. Here is an example of how I accomplished single-sourcing for a Developer Guide:

1) The document needs to be delivered to two different formats: internal developers as PDF and external developers as HTML. The PDF version includes more topics than the HTML version. To accomplish this, I wrote the source file in DITA XML, and created two different ditamaps: one for PDF and one for HTML. The PDF version ditamap includes several topics that are specific for internal users but most topics are reused by both ditamaps.

2) I used conditional text for content within a topic that is intended for different audiences by applying @audience:

<p audience=”internal”>Information for internal users</p>
<p audience=”external”>Information for external users</p>

3) I used content reference for content duplications. For example: Some APIs have same input parameters. When a parameter was first motioned, I added @id for it:

<p id=”parameterA”>Information about parameter A</p>

If the same parameter appeared later in a different document, I used @conref to reference to it:

<p conref=”filename.xml#topicid/parameterA” />

4) I used application name as a keyword variable in my document to avoid manually updates if the application name changes later. At the beginning of the ditamap, I used to define the application name as a keyword:

<topicmeta>
<keywords>
<keyword>ACTIVE Passport</keyword>
</keywords>
</topicmeta>
</keydef>

Anywhere in a topic, when needed to mention the application name, I used the reference:

<keyword keyref="AppName"></keyword>

The application name always changes for a new product. If it happens, I only need to change the keyword in the ditamap.

Organizing Web application online help

noreply@blogger.com (LISHA LI) — Mon, 03 Feb 2014 23:00:00 +0000

Organizing help content is a very important part in technical writing. I always find it’s quite challenging and always in the process of making the organization more efficient. These are the main methods that I am using to organize the help content:

· Organizing by screen: List out all the tasks and topics that relate to each main screen. This organization might help users stuck on a particular screen. We also provide tooltips and FAQ in the major screens to help users to find information faster.

· Organizing by steps: When creating an event, there are several steps in the wizard. I make each step as a category, and group all the related tasks and topics together under the step, and follow the sequence of the steps.

· Organizing by related information: Related information contains a series of logically related links placed at the end or along the side of each topic. This method provides navigation directly within the topic, where users often spend the most time.

Other methods that I also might be considering when organizing help content are:

· Organizing by audience: Audience may be identified by their roles. By doing this, you can present the topics most relevant to that audience.

· Organizing by skill level: Skill level can be divided into beginning and advanced tasks. Users new to the system can see a list of topics appropriate to beginners, while advanced users can see the more difficult topics.

· Organizing by format: Format can be grouped by videos, PDF, online help, or other formats. This helps users looking for help material based on their leaning preferences.

Digital Rights Management

noreply@blogger.com (LISHA LI) — Wed, 20 Nov 2013 00:00:00 +0000

Digital Rights Management (DRM) refers to any technology that controls how the digital content, such as audio and video, can be used and distributed.

DRM is utilized by the digital-content publisher to prevent unauthorized sharing. For example, the Apple iTunes Store formerly used a DRM system to limit the number of computers that songs allowed to be played on. Since 2009, iTunes Stores has removed DRM from its music catalog. However, television shows and movies are still encoded with DRM restriction. Each downloaded file includes information about the owner of the file and how many times the file has been transferred. The protected files can’t play on unauthorized computers.

DRM is important to digital-content publishers since it helps ensure that they will receive the appropriate revenue for their products. Although digital content is protected by copyright laws, it is very difficult to police the Web and catch law-breakers. DRM technology focuses on making it impossible to steal content in the first place. Typically, DRM encrypts or marks the content with watermark so that the content cannot be freely distributed.

Unlike iTunes, some online music stores use more restrictive DRM to allow downloaded songs only to be played while the customer subscribes to a certain music service. Customers cannot play those songs if they cancel the subscription.

DVD producers use a copy-control technology to prevent or distort copying of DVDs. E-books are usually limited to a certain number of reading devices and some e-publishers prevent any copying or printing.

Some mobile manufactures also employ DRM technology to restrict the use of their content. On Nokia Series 40 phones, the “Send” option of a DRM-protected file is grayed out to prevent users from sending such a file via MMS.

By controlling the use and distribution of digital media, DRM helps digital-publishers limit the illegal sharing of copyrighted works. DRM in some areas is considered a controversial technology, as some people argue that it takes away rights that consumers should have. However, digital-content publishers believe DRM is necessary to ensure that they are paid for their products.

SOAP and REST

noreply@blogger.com (LISHA LI) — Tue, 19 Nov 2013 23:35:00 +0000

What is SOAP?

SOAP stands for Simple Object Access Protocol. SOAP is a XML-based protocol for communication between applications. SOAP is platform and language independent. SOAP can be used over any transport protocol, such as HTTP, SMTP, TCP, or JMS.

The SOAP architecture consists of several layers of specifications for message format, message exchange patterns, transport protocol bindings, message processing models, and protocol extensibility.

A SOAP message is a XML document containing an Envelope that defines what is in the message and how to process it, a Header that contains header information, and a Body that contains call and response information.

Below is an example to show a typical SOAP operation. A GetUserDetails request is sent to a server. The request has a UserID parameter. The server returns a PhoneNumber parameter. The result is embedded inside a SOAP XML response Envelope and can be integrated into an application. The namespace for the function is defined in http://www.example.org/phonebook.

The SOAP request could be:

version="1.0"?>

<soap:Envelope

xmlns:soap="http://www.w3.org/2001/12/soap-envelope"

soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:body pb="http://www.example.com/phonebook">

<pb:GetUserDetails>

<pb:UserID>386</pb:UserID>

</pb:GetUserDetails>

</soap:Body>

</soap:Envelope>

The SOAP response could be:

version="1.0"?>

<soap:Envelope

xmlns:soap="http://www.w3.org/2001/12/soap-envelope"

soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:body pb="http://www.example.com/phonebook">

<pb:GetUserDetailsResponse>

<pb:PhoneNumber>7893652459</pb:PhoneNumber>

</pb:GetUserDetailsResponse>

</soap:Body>

</soap:Envelope>

What is REST?

REST stands for Representational State Transfer. REST is not a protocol but an architectural style for designing network applications. REST is also platform and language independent. It is a lightweight alternative to SOAP and WSDL-based Web Services. Unlike SOAP, REST is not bound to XML. CSV and JSON can also be used. REST doesn’t have standard specifications. It defines a set of architectural principles based on resources. REST uses URI and HTTP for methods GET (retrieve data), POST (update), PUT (add) and DELETE to expose resources.

A REST request for the above example could be:

http://www.example.com/phonebook/UserDetails/386

The response could be a plain text with raw value “7893652459” and is not embedded inside anything.

In REST, URIs is the equivalent of nouns. In the example, the URI method is not called GetUserDetails, but UserDetails. It is a common convention in REST design to use nouns rather than verbs to represent resources.

The example above is a simple REST request with a single parameter. REST can easily handle more complex requests, including multiple parameters. In most cases, you'll just pass along parameters in the URI. For example:

http://www.example.com/phonebook/UserDetails?firstName=Lisha&lastName=Li

Summary

In summary, both SOAP and REST are used for communication between applications. They are both platform and language independent. SOAP uses interfaces and named spaces to expose operations, while REST uses URI and HTTP methods to expose resources. REST doesn’t enforce message format, while SOAP only permits XML. SOAP has strict specification for every part of implementation, while REST gives the concept and is less restrictive about the implementation. In addition, REST follows stateless model, while SOAP has specifications for stateful implementation.

Why users can't find answers in help material

noreply@blogger.com (LISHA LI) — Wed, 30 Oct 2013 20:53:00 +0000

Why users can't find answers in help material from Tom Johnson

IE Display Issue

noreply@blogger.com (LISHA LI) — Wed, 09 Jan 2013 07:03:00 +0000

The other day, there was a strange IE display issue with my company's online help. Our help is published to HTML output to the several help servers that included six testing help servers and one production server. The help in the production server was displayed fine with IE, but the help pages in all the testing environments were displayed funny, where the top and bottom were blank and only the middle part showed up. There was no problem to display the page with all the other browsers, such as Firefox and Chrome. The help pages are just static HTML with simple JaveScripts, such as Google Analytics codes, and CSS.

When the issue was discovered by QA, at first I thought it must be the configurations in the testing environments were changed recently that had cause the issue. Otherwise, why the exactly same files in the production were totally displayed fine by IE.

I then contacted the IT department who was in charge of the servers and asked if they had changed anything in the testing environments. They denied that it was their configurations in the servers that caused the problem and insisted that it must be the JavasScripts and CSS in my help pages caused the issue. It could be, but it was very difficult to identify the problem since the production was fine, and to make things even more complicated, not all the computer's IE had the display issue. My home computer's IE displayed the help page just fine. In addition, if I opened the HTML help files by IE locally in my personal computer, there was no problem at all. So every time when I modified the help file, I had to deploy it to the testing help server to see the change.

I deleted all the JavaScripts code in the help file, but the problem still existed. I then deleted the external CSS links, the page became normal in IE, which seemed like it was the CSS that caused the problem. I thought it must be one specific class that was unable to be rendered by IE. Therefore, I removed one class at a time from the testing page to see the outcome. Finally, I was able to identify which class caused the problem, but it didn't help. The class was very simple, all it had was a background color is black. Nothing wrong with it but the IE displayed the background color as white, which made the top looked like blank. I then gave up the idea of the CSS's problem. There must be something else.

Meanwhile, someone in the IT discovered that there was a help page didn't have the IE display issue in the testing environments. The page was the homepage of another help system, which was manually created by me and was not as other pages that were automatically generated by my help publishing tool. I checked that page which had the same JavaScripts and CSS with others. I then checked the other tags in the page. To my surprise, there was different metadata tag in that file, which was < meta http-equiv="X-UA-Compatible" content="IE=9" />. I didn't know why I put it there initially. According to Microsoft, the meta tag forces a webpage to be rendered in IE 9 mode, which seemed have nothing to do with displaying CSS back background color to white. However, when I included this meta tag into my other help pages, the help pages finally were displayed normal by IE!

It was a relief, but I still don't understand why.

How to write SDK Dcoumentation

noreply@blogger.com (LISHA LI) — Fri, 13 Apr 2012 18:51:00 +0000

Good SDK documentation is extremely important for the adoption of software platforms. The following results are from a survey on SDK Documentation.

Sample code or small example apps. Although sample code was not rated significantly higher than other types of content in the multiple-choice part of the survey, it was mentioned by 61% of the respondents in their written comments. It was referred to as "the most helpful thing". Respondents wanted runnable examples that illustrate something, not just "Hello World" and talked about the desire for real world examples. There was a desire for very basic samples that would lead to more complex ones.

Help with getting started. Several respondents mentioned the difficulty of getting started with a new platform. One said, "People who make SDK documentation often don't think like a beginner who is just getting started with their SDK." Another requested "help with learning curve," and another suggested "going all the way down to the bottom (installation and setup of tools)". Another commented, "Once you've got the basics, it's easy to begin poking around on your own. But if you can't get started, that's frustrating."

Explanation of why. Eight of the respondents mentioned that it was important to understand why the software platform or individual APIs should be used. One summarized this as "Why, why, why, not what, what, what." Another cautioned that this should be from a programmer's point of view, and not the marketing department. Case studies and real-world examples were desired.

Accuracy is critical. Respondents wanted "absolute mathematical precision" and "no ambiguity". One respondent said that "the most unhelpful thing in SDK documentation is incorrect information," and another said, "Sometimes misinformation is worse than no information at all." This suggests how valuable technical reviews are; unfortunately, technical writers often find that getting developers' time for reviews is very difficult.

Ability to find information easily. This theme came up in several ways. Heavy-cross referencing and indexing was mentioned, as well as improving search capabilities. The ability to come at the information in different ways (by topic, alphabetically, etc.) was also mentioned.

Good overviews. 30% of the respondents mentioned overviews. Respondents desired "a high level overview of the concepts that bridges into the detailed API documentation" and said that it was "missing from many API documentations."

Content should be written by someone other than the developer. Two developers brought up this issue. One said it was not useful when documentation "is written by the same person that wrote the API. To them, everything makes perfect sense and requires little description." Another said, "Developers should only be the Subject Matter Experts, not the authors."

Flow diagram. When explaining tough concepts, a good flow diagram goes a long way and wins developers hearts.

Web APIs. Authentication is often required for Web APIs, and this needs to be documented in detail as well. If developers need API keys, be sure to give them step-by-step instructions on how to obtain these. Also, don’t forget that Web APIs are built on top of HTTP, which is an incredibly rich protocol. You may have HTTP-related information that requires documentation, such as caching, content type and status codes.

In conclusion, sample code, overviews, and help getting people started should be given the highest priority. Content needs to explain why something should be used in addition to how it is used. Also, because accuracy is considered critical for documentation users, managers need to be sure that the developers who created the APIs are available for discussions with the writers and for technical reviews.

In the end, the best formula for effective SDK documentation is the combination of good writers who know how to write for a developer audience and developers who are willing to take the time to work with them.

XMetaL PDF via RenderX TOC indenting problem

noreply@blogger.com (LISHA LI) — Fri, 09 Dec 2011 23:38:00 +0000

When generating PDF output from XMetaL 6.0, if you are frustrated with the TOC of the "XMetaL Enhanced PDF via RenderX XEP" that does not have indenting of the topic title hierarchy at all, I have a simple solution for you:

Just copy C:\Documents and Settings\lli\Application Data\SoftQuad\XMetaL Shared\DITA_OT\demo\xmfo\cfg\fo\attrs\toc-attr.xsl to the following folder to override the same file in this folder:

C:\Documents and Settings\lli\Application Data\SoftQuad\XMetaL Shared\DITA_OT\demo\xmfo\Customization\fo\attrs\xm-cfg

Note: you should back up the original file in the second folder before the copying just in case.

Content Reuse Strategies for Building Multiple Markets Online Help

noreply@blogger.com (LISHA LI) — Fri, 30 Oct 2009 22:28:00 +0000

The project that I am currently working on is to build help for a web-based application that supports cross-market event registrations.

We write help in DITA. We use DITA OT to publish online help in HTML format, and a tool that I created to delivery embedded XML format help to the application user interface.

To maximum the reuse of content, three levels of strategies are adopted:

Topic level reuse
Paragraph level reuse
Phase level reuse

Topic level reuse

A ditamap can reuse content in the topic level. We have core content for all markets, and market specific content for a specific market. Since maps only processes topics in the same directory as the map, or in the sub-directories of the map's directory. The structure of the content should be maps of each market are stored outside of the core and makets directories. A second level of maps can be created to organize a set of topics for one feature within the core or market directories. This second level maps can be reused by different market maps.

Paragraph level reuse

Conditional text can reuse content in the paragraph level. If there are only one or two sentences difference in a topic for different markets, you can add an attribute to indicate which market this paragraph belongs to. By adding a filter ditaval file to the DITA OT, maket specific paragraph will be delivered to each market.

Phase level reuse

DITA 1.2 keydef element can reuse content in the phase level. The keydef element can be used in combination with the keyword element in a ditamap to define and set "variables" for small pieces of content that may change fairly often, such as UI labels, product name, version etc.

These keys (or variables) can be redefined later in the same map or in another map and all topics that reference the keys will automatically pick up the changes. For example, you can put a particular product name into a DITA map, and indicate in topics where you want the product name to appear. When you generate output using the map, its topics will display the product name in the appropriate places.

Keydef.ditamap

<map>
<keydef keys="marketname">
<topicmeta>
<keywords>
<keyword>Camp</keyword>
</keywords>
</topicmeta>
</keydef>
<keydef keys="eventname">
<topicmeta>
<keywords>
<keyword>Camping sites</keyword>
</keywords>
</topicmeta>
</keydef>
<topicref href="eventsetup.dita"/>
</map>

eventsetup.ditamap
<concept>
<title>Event Setup</title>
<conbody>
<p>You can use ActiveWorks <keyword keyref="marketname"/> to set up
your <keyword keyref="eventname"/>.</p>
</conbody>
</concept>

How to create a DITA OT plugin

noreply@blogger.com (LISHA LI) — Fri, 30 Oct 2009 19:03:00 +0000

When you use DITA OT to publish your DITA content, you might need to customize DITA OT XSL transformation. To make your DITA OT changes portable, you can create a DITA OT plugin.

To create a plugin, you need to first create one or more new or overridden templates xslt files, second create a plugin.xml file to point to your xslt files, and then install this plug-in to your DITA OT.

To create templates

Create a folder in dita-ot/demo to store your plug-in, such as my-plugin.
Create a folder to store your xslt files in dita-ot/demo/my-plugin, such as xsl.
Create a new xslt file to contain the template. It's better that one xslt file only include one function.

To create plugin.xml

Copy a plugin.xml file from any existing plugins into dita-ot/demo/my-plugin.
If there are more than one <feature> elements, delete the rest and only keep one <feature>.
Change the value in the remaining element to point to your new xslt files, separated by commas: < feature extension="dita.xsl.xml" value="xsl/yourxslt1.xsl,xsl.yourxslt2.xsl" type="file" / >

To install your plugin

In your dita-ot folder, run startcmd.bat.
In the cmd.exe window, type: ant -f integrator.xml.

The plugin that you have created can be easily packed and installed once you upgrade your DITA OT, or pass to others.

How to perform your own transformation using DITA-OT

noreply@blogger.com (LISHA LI) — Mon, 20 Oct 2008 23:35:00 +0000

This task assumes that you have DITA-OT appropriate installed in your computer.

DITA-OT transform DITA XML documents to other formats. However, you can tranform any XML document from command line using the Xalan XSLT processor, which is included in the DITA-OT.

To do this:

Have your own XSL stylesheet written and make sure it do what you expect with the XML source files they are designed to transform. You can try out using a browser.
In the DITA-OT folder, click to run startcmd.bat, which automatically set the system environment variables for you.
The command line for most standard transformations is as follows:
java org.apache.xalan.xslt.Process -in xmlSource -xsl stylesheet -out outputfile

where xmlSource is the XML source file name, stylesheet is the XSL stylesheet file name, and outputfile is the output file name.

If you want the output to be displayed on the screen, simply omit the -out flag and argument

Note:If you are using an external DTD or Schema, you need to have it to be found by the processor. Or you can just delete it from the source file. Otherwise, the processor will complain that it can't find the DTD or Schema.

Remix An User Manual by FLOSS Manual

noreply@blogger.com (LISHA LI) — Mon, 08 Sep 2008 22:55:00 +0000

The first time when I was using iGoogle, I though that it would be great if a user manual can be customized by the user using drag-and-drop operation. And now it comes true. Someone is really doing this - FLOSS Manual.

In the Remix section of the FLOSS Manual, you can just asseble each chapter or each section of a user manual as you want and then generate to PDF or HTML format. The operation is as simple as you adding widget to your iGoogle homepage.

How to embed YouTube video into DITA

noreply@blogger.com (LISHA LI) — Mon, 25 Aug 2008 18:26:00 +0000

You can embed an YouTube flash video into your DITA document using the <object> element.

Get the URL of the movie value from YouTube website. For example: http://www.youtube.com/v/EfmQB0stRRI&26hl=en
Replace any "&"(ampersand) characters in the URL with "%26"
Use that URL in the following DITA <object> element:

<object data="http://www.youtube.com/v/EfmQB0stRRI%26hl=en"
height="355" id="VideoPlayback" type="application/x-shockwave-flash"
width="425">
<param name="movie"
value="http://www.youtube.com/v/EfmQB0stRRI%26hl=en"/>
<param name="FlashVars" value="playerMode=embedded"/>
<param name="allowScriptAcess" value="sameDomain"/>
<param name="scale" value="noScale"/>
<param name="quality" value="best"/>
<param name="bgcolor" value="#FFF"/>
<param name="salign" value="TL"/></object>

Which element to choose as the reusable DITA component

noreply@blogger.com (LISHA LI) — Wed, 20 Aug 2008 22:39:00 +0000

Writing a reusable component allows you to reuse a piece of text insets in your DITA document and reduces the cost for maintenance.

Reusable Candidates

The following are elements reuse candidates:

product name
installation paths
icon refrence
note(restrictions, prerequisites, tips)
individual steps

Element to Choose

The reusable component itself is a DITA XML file. It should follow the DITA vocabulary rules. In the reusable component file, you can choose most of the DITA elements to wrap the reusable text; however, which element makes the component most reusable?

For the semantically significant content, use the correct semantic elements, such as: filepath, varname, and cmdname
For the non-semantic strings, choose the least restrictive element type:ph

Syntax

Source:<element id=“element-ID”>content (including subordinate elements</element>
Reuse:<element conref=“source-file.dita#topic-ID/element-ID”></element>
For example:
Source:<ph id=“otk">DITA Open Toolkit</ph>
Reuse: <ph conref=“contentReuse.dita#conrefs/otk"></ph>

How to Inlucde A JS File in XSL

noreply@blogger.com (LISHA LI) — Fri, 08 Aug 2008 19:10:00 +0000

In my project, I need to include an external javascript(js) file in xsl. At first, I tried to include a script element in the head written in HTML syntax as :

<script language="Javascript" src="filename.js"></script>

When transfering to HTML, it became to:

<script language="Javascript" src="filename.js" />

Without the closing tag</script>, the script element was not recognized by the browser.

To solve this problem, I have tried a lot of methods, such as adding text to the empty script element as:

<script language="Javascript" src="filename.js">1</script>.

Although it worked fine, the useless text between script tag looked so unprofessional.

At last, I came across a way to make this work. Rather than including script as an element, I included a line of plain text using <xsl:text>:

<xsl:text disable-output-escaping="yes"><script src="fsq.js" language="Javascript"</xsl:text><xsl:text disable-output-escaping="yes"> ></xsl:text><xsl:text disable-output-escaping="yes"></script></xsl:text>

This line became <script language="Javascript" src="filename.js"></script> in HTML.

How to Embed Multimedia Video in DITA

noreply@blogger.com (LISHA LI) — Fri, 25 Jul 2008 21:44:00 +0000

This document explains how to implement multimedia video in DITA and how to transfer them to HTML format.

Supported Video Formats

The following are currently the most popular multimedia video formats on the Web:

The Shockwave (Flash) Format (.swf)
The Windows Media Format (.wmv)
The AVI Format (.avi)
The MPEG Format (.mpeg)
The QuickTime Format (.mov)
The RealVideo Format (.rm)

Web browsers use the <object> element to render these video files. The <object> element has two child elements: <param> and <embed>. The <param> element defines run-time settings for the object. The <embed> element is added to support browsers that don't support the <object> element. A browser that can parse the object element will ignore the <embed> element. The object element will be used by new browsers that support ActiveX controls. Older browsers will use the embed element.

Based on my research, the newer version of IE (IE 5 and later) accepts the <object> element for all six media types, while other browsers such as Firefox accepts the <object> element for only Flash(.swf) and WMV formats.

The DITA standard doesn’t allow <embed> element within the <object> element. To solve this problem, you need to modify the DITA-OT dita2htmlImpl.xsl to include <embed> element while transforming .avi, .mpeg, .mov, and .rm format video. You can also modify the DITA-OT xsl to support other object formats.

Implement in DITA

<object> element

DITA's <object> element corresponds to the HTML <object> element.

Attributes

The following attributes of the <object> element are required to render video formats:

classid: the format of the classid string is "clsid:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" for registered Microsoft ActiveX Controls. It tells the browser which media player to use to play the video.
data: the location or URI of the video file. For .avi, .wmv, and .mepg formats, the full direct URI is needed. Other formats only need relative URIs.
type (MIME type): indicates the video type.
width: the width of the video file in pixels.
height: the height of the video file in pixels.

The following table lists the value of classid and MIME type attributes of the six video formats:

format	classid	MIME Type
swf	Can be eliminated	application/x-shockwave-flash
wmv	Can be eliminated	video/x-ms-wmv
avi	clsid:22D6F312-B0F6-11D0-94AB-0080C74C7E95	application/x-mplayer2
mepg	clsid:22D6F312-B0F6-11D0-94AB-0080C74C7E95	application/x-mplayer2
mov	clsid:02BF25D5-8C17-4B23-BC80-D3488ABDDC6B	video/quicktime
rm	clsid:CFCDAA03-8BE4-11cf-B84B-0020AFBBCCFA	audio/x-pn-realaudio

<param> element

At least one child <param> should be included in a <object> to identify the location of the video data file.

Sample Code

The following lists the coding used to implement the video in DITA for the above example:

SWF
<object width="700" height="700" type="application/x-shockwave-flash" data="sample.swf">

<param name="src" value="sample.swf" />
<param name="autostart" value=" false" />
</object>

WMV
<object type="video/x-ms-wmv" data="http://domainname/video/wmvfile.wmv"
width="320" height="260">
<param name="src" value="http://domainname/video/wmvfile.wmv" />
<param name="autostart" value="false" />
</object>

AVI
<object type="application/x-mplayer2" classid="clsid:22D6F312-B0F6-11D0-94AB-0080C74C7E95" data=”http://domainname/video/avifile.avi”>
<param name="src" value=" http://domainname/video/avifile.avi" />
<param name="autostart" value="0" />
</object>

MPEG
<object type="application/x-mplayer2" data="http://domainname/mpegfile.mpeg"
classid="clsid:22D6F312-B0F6-11D0-94AB-0080C74C7E95">
<param name="src" value=" http://domainname/video/mpegfile.mpeg" />
<param name="autostart" value="false" />
</object>

QuickTime movie(mov)
<object type="video/quicktime" width="450" height="230" data="Apple.mov"
classid="clsid:02BF25D5-8C17-4B23-BC80-D3488ABDDC6B">
<param name="src" value="Apple.mov">
<param name="autostart" value="false" />
</object>

Real Video Format
<object type="audio/x-pn-realaudio" width="320" height="240" data="rmfile.rm" classid="clsid:CFCDAA03-8BE4-11cf-B84B-0020AFBBCCFA">
<param name="src" value="rmfile.rm" />
<param name="autostart" value="false" />
</object>

Using SFTP in VB.net

noreply@blogger.com (LISHA LI) — Tue, 13 May 2008 17:05:00 +0000

In my last blog, I talked about using ftp in vb.net. This time I will introduce a way to use SFTP in VB.net.

Same as call Windows ftp.exe in VB.net, you can call an SFTP client. Since Windows dosen't include any default SFTP client software, you need to find and install one. I used an open source free SFTP client called WinSCP, which supports scripting.

WinSCP has an very cool command-"synchronize". It can synchronize remote directory with your local.

The following is an example scripting txt file:
open username:password@hostname
synchronize remote [local directory] [remote directory]
chmod 777 [remote directory]\*.*
close
exit

After having created the scripting file, include the following line in a batch file and let VB.net to call the batch file:
winscp.exe /console /script=example.txt

Using FTP in VB.net

noreply@blogger.com (LISHA LI) — Sat, 03 May 2008 00:06:00 +0000

A easy way to use ftp in vb.net is to call Windows ftp.exe.

First, you need to create a txt file with all the ftp commands.

An example ftp.txt:

open hostname portnumber
username
password
put filename
bye
exit

Then, in your vb.net script, use Shell to call ftp.exe:

ProcID = Shell("ftp -s:ftp.txt")

DTD FAQ

noreply@blogger.com (LISHA LI) — Wed, 23 Apr 2008 03:28:00 +0000

How to create an attribute and enforce a limited number of choices?

Enumerated attribute values

Syntax:

<!ATTLIST element-name attribute-name (eval|eval|..) default-value>DTD example:

<!ATTLIST payment type (check|cash) "cash">

Example 1.

Example 2.

This enforces the ALIGN attribute of the P element to have the value of either LEFT, or RIGHT, or CENTRE. A default can be supplied as follows:

<!ATTLIST P ALIGN (LEFT|RIGHT|CENTRE) "LEFT">

How to define rules for elements with more than one attribute, and if so how might I do it?

Defines the attributes list for the specified tag. You can declare multiple attributes at the same time, each with its type and value. An attribute can be of type CDATA, or it can be an item of a collection. Its value can be fixed, implied or required (see below). Here are a few examples:

Example. 1

<?xml version="1.0"?>

<!DOCTYPE payment [

<!ELEMENT payment (#PCDATA)>

<!ATTLIST payment type CDATA "check">

<!ATTLIST payment bank CDATA "TD">

test

</payment>

Example 2.

<?xml version="1.0"?>

<!DOCTYPE payment [

<!ELEMENT payment (#PCDATA)>

<!ATTLIST payment type CDATA "check" bank CDATA "TD">

test

</payment>

What are EMPTY Elements and how do I define them?

The word "EMPTY" designates the element has no content. Here's an example from the HTML 4 transitional DTD:

Example:

<!ELEMENT ADDRESS (STREET, CITY, STATE, ZIP, COUNTRY)>

<!ELEMENT STREET EMPTY>

<!ELEMENT CITY EMPTY>

<!ELEMENT STATE EMPTY>

<!ELEMENT ZIP EMPTY>

<!ELEMENT COUNTRY EMPTY>

DTD Attribute Value Declarations

noreply@blogger.com (LISHA LI) — Tue, 22 Apr 2008 17:20:00 +0000

Within each attribute declaration, how the value will appear in the document must be specified as following:

#DEFAULT: the attribute has a default value.
#REQUIRED: the attribute value must be included in the element.
#IMPLIED: the attribute dose not have to be included
#FIXED: the attribute value is fixed.

Cardinality of A DTD Element

noreply@blogger.com (LISHA LI) — Tue, 22 Apr 2008 17:10:00 +0000

An element's cardinality defines how many times it will appear within a content model. DTDs allow four indicators for cardinality:

[none]: only once
?: 0 or 1
+: 1 or more
*: 0 or more

How to Valid a XML File

noreply@blogger.com (LISHA LI) — Tue, 22 Apr 2008 17:06:00 +0000

To valid your XML file, you can:

Use an online validator, such as: http://www.stg.brown. edu/service/xmlvalid/
Use XML editor, such as: XML SPY or XMLETAL

What are Building Blocks of XML Documents?

noreply@blogger.com (LISHA LI) — Tue, 22 Apr 2008 04:52:00 +0000

Elements:
Tags: tags are used to mark up elements.
Attributes: attributes provide extra information about elements.
Entities:
PCDATA: PCDATA means parsed character data between start tags and end tags.
CDATA: CDATA means the text that will not be parsed which is inside a tag. It is the attribute in DTD.

What is a DTD

noreply@blogger.com (LISHA LI) — Tue, 22 Apr 2008 03:48:00 +0000

DTD stands for Document Type Definition. It is an extra rules that a XML file must conform to. We say a XML file is valid if it does confirm to the rules of a DTD.

DTD are written using EBNF(Extended Backus-Naur Form) not XML syntax.