The GetPublished user guide

By: Tom Lam (borland)

Abstract: Read this user guide to learn how to submit articles or translations for articles, and to also learn what to expect during the editing process

    Publishing your article using the GetPublished System

    What it does

The GetPublished system allows anyone with an account on bdn (that’s you!) to submit an article for publication or offer a translation for an existing article. The system manages the necessary review steps, keeps track of required paperwork (tax forms and contracts), and otherwise acts as the publication entrance to bdn.borland.com, Borland’s developer community web site.

    Articles

Once you’ve logged in to BDN, and entered the GetPublished area you can submit your article as either Microsoft Word produced .DOC format, RTF or XML; use the browser based visual HTML editor (this works best for Internet Explorer users under MS Windows), or submit an HTML file of your own creation (combined with associated graphics into a .ZIP file if desired).

GetPublished processes your document upon submission: creating a table of contents along the way, extracting your graphics, making appropriate sized thumbnails, etc. The converted HTML version will be a candidate for publication; but you can still get access to your original document version version for further editing.

    Warranties & Tax Forms

Before we can do anything with an article you submit, you must complete a contract referred to as “Warranty of Assignment of Rights Agreement”. We prefer that you complete this electronically via the GetPublished web site since that keeps the process automated; alternatively you can print and sign a hardcopy and return it as a scanned email attachment or fax.

For every GetPublished type article, we must have an Agreement for each and every article or version thereof that you submit for publication. Note that the GetPublished system is most often used to work with articles of the GetPublished type, but also allows you may be able to select other article types for your submission if your account has the corresponding privileges. Some article types do not require a warranty, and are not eligible for payment.

The case is similar with tax forms, unless you decline to receive payment for your article(s), in which case no tax forms are required. The tax forms must be reviewed and accepted by our editorial staff; until they have done so, you will still be reminded to submit forms.

Only one tax form is required of you; it will cover all articles you submit.

We encourage you to complete the Warranty Agreement when first submitting an article, but you can do it at a later time by clicking on ‘My Missing Warranties’ in the navigation area that appears on the left of the browser page.

Note that until you complete the Warranty Agreement or otherwise submit a warranty to us we will be unable to review your document. Your document will wait, and wait, and wait. If you’ve submitted an article and have not heard back from us, check to make sure that you also submitted a warranty.

    Review, Approval, Launching

Peer review is our key to quality, as it is in academic journals. We have a team of editors/reviewers who will review your submission for clarity, accuracy and completeness. GetPublished allows them to review, suggest modifications to, actually edit, and finally approve your submission. They use the same interface that you do to view and move articles along, but are presented with additional options appropriate to their role. These steps are covered in a separate document, A Reviewer’s Guide to GetPublished, coming soon.

    Publication

There is not much to this step; and it is covered in the bdn Editors Guide rather than here.

    Steps to publication

This section covers the steps you must complete to submit an article for publication. It presents complete instructions, with screen captures. Details of formatting your article in Word or HTML are covered separately; see that section.

Note that the order of some of these steps is somewhat arbitrary. In fact, we encourage you to go ahead and submit your tax form prior to submitting an article. Similarly, you could upload your biography and photo apart from any particular article.

    Go to the GetPublished home page.

To do so, select GetPublished from the More Resources Dropdown list on the top navigation bar of bdn, as shown below. If you are not currently logged in (and your bdn cookie is not set) you will be redirected to the login system. You must always be logged in to use any GetPublished functionality, including viewing your articles in process.

Note that the visual HTML editor works best with Microsoft’s Internet Explorer (Windows); so if you plan to use the editor, save yourself some time and log in to the site with that browser.

Hide image
Click to see full-sized image

This takes you to the GetPublished home page, which is also your My GetPublished page.

Take a look at this page. To the left it has the navigation bar for GetPublished, described in detail in the Navigating GetPublished section of this document. Right and center, in the Tasks area, are a reminder to submit the appropriate tax form (partially concealed in this screen capture by the drop down menu), and links for My articles and ‘Submit a New Article’. In your case other tasks might appear here, depending on your roles and the status of your articles. For example, if you have articles without a warranty, you’ll get a task listing articles missing warranties and allowing you to sign them electronically.

    Submit your article

1. Click on the ‘Submit New Article’ link in the blue Articles box. (Note that there is also a ‘Submit New Article’ link on the left navigation bar if you click on the Articles link first.)

Hide image
Click to see full-sized image

2.        You will be presented with the Submit Article page below:

Hide image
Click to see full-sized image

2a.      Fill out the Title and Abstract fields, and select an appropriate language from the pulldown if your article is not in the default which is English. The Article Type will be GetPublished and is a display only form element which does not accept input for most users; your account profile may include permissions to create other content types, in which case this control will be live and offer alternate values.

2b.      Go to File Format and choose either Microsoft Word (the default), or HTML. The area below will change according to your selection. HTML will bring up a visual editor.

3a.      Microsoft Word: upload your .DOC, .RTF, or .XML file. .DOC is the preferred format, especially if your article includes graphics. .RTF conversion is sometimes incomplete.

--or—

3b.      HTML: use the browser based visual HTML editor to compose your article, or upload either an HTML file, or a zip file containing your HTML file and associated image files. For details on how to format your HTML file, see that section, below.

4.        Select Community Mappings. We request that you do not leave the mappings as the default None|None|None. Please choose mappings appropriate to your article; they will not only ensure that it appears in the community(ies) most appropriate, the mappings also help to put it on the task list of the best reviewer for your material.

Choose as many mappings as are relevant to your submission.

On rare occasions the mapping area may not work—if so, check your browser settings to make sure that you have JavaScript enabled, as this functionality requires JavaScript.

Notes and Caveats

The form requires that you fill out both the Title and Abstract fields. These values will replace those from within your Word document, so don’t be surprised. (Since the import of HTML documents does not include the HTML <TITLE> tag, HTML Titles are always ignored and replaced by the form values.)

Further instructions on how to format your Word document for optimum display on bdn—including the limitations of bdn’s Word conversion—can be found in that section, below.

When in Edit mode, ignore the Redirect To and Link To fields; these do not work properly at present. (These two fields are not present on the page for creating a new article, as they are tools to facilitate maintenance of legacy articles, and are not intended to be used for new ones).

    Submit your warranty of originality

Upon successful upload of your file you will automatically be redirected to the Agreement page similar to that below. (This one is scrolled down to show the bottom of the form.)

Hide image
Click to see full-sized image

We prefer that you click agree at this point. You will then be able to ‘sign’ the Agreement with a couple of clicks on a web page and be done with it. The top portion of this page (it’s a long one) is below. Note that it’s filled out with your name, the title and ID of the article.

If you select I Do Not Agree, you will be prompted to download, print, sign and either fax or scan and email your Agreement back to Borland. More work for both of us!

Agreement Form Page

Hide image
Click to see full-sized image

You can ‘offer the article free of charge’ by checking on the box of that name which is in the middle of the page. This is, of course, optional and up to you.

Hide image
Click to see full-sized image

Click on the I Agree radio button at the bottom and hit the OK button and you’re done. You will be redirected to the Edit Article page for the article you just submitted.

    Preview your article

To make sure that you uploaded the file you intended, and that the conversion to HTML worked correctly, your next step should always be to preview your article. To do so, click on the magnifying glass in the right area of the row of the Article Versions and Languages table of the Edit Article page.

Hide image
Click to see full-sized image

This is a good time to look at the other things you can do with your article.

* The red X next to the magnifying glass allows you to delete this article.

* The little lightning bolt, if present (and it probably will not be for you), allows you to approve the article for publication.

* The Title, in this case the rather ugly gp test .doc2, is a link to edit the article.

Moving down from the Article Versions and Languages table, you get to the Submit New Versions area. This is exactly the same form you had before, to submit your first version.

Hide image
Click to see full-sized image

Notes about Versions and Languages

Our web site is fully multilingual, and you can have as many versions of your article in different languages as you (and others) can come up with.

Editing a Live (Published) Article

Do you have an article that has been approved and launched in need of revision? Go ahead and make the revisions by submitting a new version: you can have both a live and draft version of the same article in the same language at the same time.

The screenshot below shows two versions—live and draft—for the same article.

Hide image
Click to see full-sized image

You can only have one draft version of your article in each language. You can, however, have both draft and live versions: so if you would like to revise an article which is currently live, go ahead and submit the revision. The live version will remain live, and the revised version will then go through the review cycle.

Uploading your article again in the same language already present overwrites the previous draft version.

    Edit your article

You can edit your article, or any version of it that you’ve created, at any time prior to publication. To do so, locate the version you want to edit in the Article Versions and Languages table and click on the article title or ID.

‘Editing’ here could mean replacing the article by uploading a new .DOC or other file, or by editing the HTML using the visual editor. (If you change the File Format from Word to HTML for an existing article, the visual editor brings up the converted version).

Lost your original .DOC file? Bdn stores the original version as well as the converted version, you can download it (or any of the extracted graphics) from the Files list at the bottom of the Edit Article Version page, as shown below. Note that the file list does not appear on the Edit Article page; you must bring up the Edit Article versions page by clicking on the article title in the Article Versions and Languages table.

Hide image
Click to see full-sized image

Note that there is no way to directly delete this or other files but there is no need to. They will be automatically deleted for you if no longer referenced. You may delete the version or article in its entirety. Upload a new version of your article without the files (and the same language as your original): the new version will overwrite the previous version, and images no longer included will be deleted.

    Submit your tax form

If you would like to be paid for articles you submit for publication, we need to get a tax form from you. You can download the appropriate form from the Downloads area at the bottom of the left navigation bar in the GetPublished area. Use the W9 if you are a resident of the USA; or the W8 if you live outside the USA.

Download, print, sign and scan your form. Then go to the My My Tax Forms page in the My GetPublished area. You will see a page like that below; put in the date you signed the form and pick the scan file for upload.

Your scan can be .GIF, .PDF, or any other graphics format. (Please use a common one so we can read it).

Click Submit.

Hide image
Click to see full-sized image

Once your form file has been uploaded, the My Tax Forms page redraws with the submitted form(s) listed at the top: Hide image
Click to see full-sized image

Your next step should be to preview the form. To do so, hit the Preview Icon to the right.

Assuming that your form uploaded correctly, you’re done. We will review and approve your form and then be ready to pay you for your bdn submissions.

    Create your biography

We recommend you create a biography for yourself and upload a photo. We plan to display these along with the content of your article(s).

To do so, click on the My Information link in the My GetPublished area. You’ll get a page like the one below; fill it out as you wish and pick a photo you like.

Notes

Size: your photo will not be resized on upload, so upload a reasonably sized one, such as 200 x 300 pixels. Current plans call for resizing to fit in a 100 x 100 pixel box and displaying with the article.

Replacing your image: Check the Clear Image check box if you would like to replace your previously uploaded image. The text refers to the Images page as the other way to do so, but this is not currently publicly available.

Hide image
Click to see full-sized image

    Approval

Our Editors will go over your article, perhaps make comments and suggest revisions, and (you hope) eventually approve your article for publication. While you may have to work with them on revisions, the approval is not in your hands. We’re including it as a step here for the sake of completeness, as it is a part of the publication process. Besides, you might sometime become an Editor as well.

    Formatting your article for this site

This section provides guidelines on how to set up your document for publication. It has two variations: Word and HTML. Word covers the .DOC format (recommended), and .RTF (Rich Text Format), and word-generated XML.

    Word or HTML?

Your choice of Word or HTML depends both on which one you are comfortable working in and the nature of your article. Word is easy…but be advised that bdn’s current Word conversion has the following limitations; if these are significant to you, you may want to use HTML instead.

  • * Word’s default bullet & numbered lists styles are not converted. These are not converted to <Uls> or <Ols>, but into regular paragraphs. We are working to add this to the conversion tool.
  • * No boxed text: if you want to have this kind of formatting in your article, you will have to put your text in a table and create borders with Word’s table borders controls.

    Microsoft Word

Many authors work in Microsoft Word, so we have implemented automatic conversion of Word files to HTML, complete with Table of Contents generation, creation of thumbnails, collapsible sections, hide-able images. Note that if you have an existing TOC in your Word file, it will be replaced by a generated one in the HTML translation. Word text tagged with the Source Code style (part of the bdn.dot template) will be translated into PRE text.

Word tables are converted, and most border styles for tables are translated correctly.

    The BDN template

We recommend basing your Word document on the BDN template. It defines Heading 1..Heading 6 to appear similarly to their bdn-styled HTML correspondents, has a style for program code which is translated to monospaced <PRE> HTML, and has special styles for Title and Abstract (though these are currently overridden by the form values upon submission.

You can download the bdn.dot file from the Downloads area at the lower right of the navigation bar.

Suggestion: locate your template directory prior to downloading the template.

To locate where Word looks for User Templates such as the bdn.dot, go to Tools|Options|File Locations and see where User Templates is set to. Then download the bdn.dot to that directory.

To create a .DOC file from that template, choose File|New from the file menu (if you just click on Word’s blank file icon you are not asked which template to base it on). Depending on the version of Word you’re using, you may then choose General or User tabs to bring up the bdn.dot file.

Some versions of Word will automatically create a blank document based on the template if you double click on it; older ones may not.

    Conversion Features

These were covered briefly above. Most notably when Word documents are converted to HTML

  • * Heading 1 and other headings are converted to their corresponding <H1> counterparts.
  • * Table of Contents are generated from Heading 1 to Heading 3 (Heading 4 and smaller are not included in the TOC).
  • * BDN Bullet & BDN Numbered List styles translate to their HTML equivalents.
  • * Images are converted to .PNG files, thumbnails created for each as well. Cropping within Word does not carry through.
  • * Hyperlinks are retained.
  • * Character formatting (BOLD, underlined and ITALIC) is retained.
  • * SourceCode style (available in the bdn template) is converted to a <PRE> formatted monospace font, complete with a box around it and grey background.
  • * Syntax highlighting in various languages will be supported in the near future.
  • * Headers and Footers are ignored.

    Conversion limitations

  • * Bullets and numbered lists created using Word’s default formatting styles (the Bullet & Numbered tools on the formatting tool bar) are converted to regular paragraphs.
  • * No fancy formatting is allowed.
  • * Graphics that have been cropped in Word become uncropped and the full sized originals are displayed.
  • * Small graphics may become larger.
  • * Footnotes, Endnotes and Annotations are removed.

    Conversion work arounds & other tips

You can edit the converted HTML for your article—even if you submitted a .DOC file--if you have lists or otherwise would like to polish the formatting performed the automatic conversion. I discovered this quite by accident.

Suggestion for bullets—either put the text in a table with a blank left column, or preface paragraphs with *s to indent.

Do not use the Body style; use Normal instead.

Bold where is was not? If you have text that did not display bold in Word but does after the conversion, check to make sure that it has the appropriate Normal style, and no bold overrides. The easiest way to do this is select the text, choose Normal from the style menu, and then CTRL-Space (Word’s shortcut to remove all character formatting overrides and restore to the default for that style).

To edit converted HTML from a .DOC file

Click on the title of the article in the Article Versions and Languages table, as described above. When you are presented with the Upload Article form, complete with Microsoft Word selected as the format, simply change the format to HTML. Voila, the HTML visual editor appears below the file upload form, complete with your converted article. Now you can go ahead and fix bullet lists, etc.

The one disadvantage of this approach: your original .DOC file will be deleted from the server, and for future edits you will have to either edit the HTML version, or upload the .DOC file again from your computer.

    Using the visual HTML editor

If you have a simple article without graphics, or you just want to fix a previously submitted article, the browser-based editor may work for you.

Note that the system generates a Table of Contents (TOC) for you based on the headings in your document.

    Visual HTML Editor capabilities and limitations

The editor allows you to make headings, bold, italisize, and underline text, monospace (program) font, and change size and color. Left, center and right alignment are supported as well. Most importantly, it supports bulleted and numbered lists.

Note that the features supported use plain non-CSS html; it’s back to our old friend the pre-CSS <FONT> tag. However we strongly discourage the use of the FONT tag: keep it simple and have your article formatted consistently with the other articles on the site.

The editor does not create tables nor add images, but you can do simple edits to text in tables and pre-existing images will display properly.

    Your own HTML

If you like to use Dreamweaver, FrontPage or any other HTML generation tool you are welcome to do so. The system will still generate a TOC for you. The limitations are listed on the HTML upload area; they are recapped below:

* No paths are allowed in <IMG> references. See below for details.

* Scripts are not permitted and automatically removed.

* The <HEAD> portion of your document is removed; only the <BODY> portion is retained.

* <STYLE> tags are removed, and custom CSS is discouraged. This is partly a question of sitewide consistency, and partly to simplify maintenance.

    Images and .ZIP archives

The most important thing to keep in mind when working with images is store them in the same directory as your HTML file so that all reference are unqualified and local. Any path information, be it to ‘/’, ‘images/’ or whatever will be removed and your images will not appear.

If you are creating your document in Word we recommend that you use BDN’s conversion tool. If you insist on performing your own Word HTML conversion, make sure that the ‘Organize files in a Supporting Folder’ option is not checked. (You can find it under Tools|Web Options in the Save for Web dialog box, or other location according to your version of Word.)

Create a .ZIP archive of your images and HTML document; that is the easiest way to upload them all.

    Revising HTML

You can revise and re-upload your HTML and images. Note that you must re-upload all of your images when re-uploading your HTML. This is true even if your images have not changed and the references to them have not changed.

    Navigating GetPublished

This section covers the navigation of the GetPublished area. It describes each item of the left navigation bar for that area.

The GetPublished area has five sub areas:

* My GetPublished

* Articles

* Authors

* Settings

* Downloads

Those of most interest to you as an author will be the first and last; the middle ones are particularly relevant to editors. These are discussed below.

    My GetPublished

This is your ‘home page’ for the GetPublished system. The links and text presented will vary according to your status in the system. For example as a new author you will get a reminder to submit a tax form until you do so and your form is approved. A typical MyGetPublished page looks like this:

Hide image
Click to see full-sized image

    My Articles

This link—note that it is both the topmost item under My GetPublished and also on the right blue Articles area—takes you to a custom page which lists any articles you have in process, and offers you the link to Submit a New Article at the top. Your page will look something like this if you have submitted two articles. Note that you will not have the rightmost column unless you are a publisher for bdn.

Hide image
Click to see full-sized image

The table presents a row for each article that you’ve submitted using this bdn login. Going from left to right across the table the columns are as follows.

Col. #

Contents

Values

Action/Link

Notes

1

Language

Plain icon Hide image
languageicon indicates original article language

Icon with Globe
Hide image
globe indicates that this is a translation
EN-English,
JP-Japanese, etc.

Edit Article

Languages are listed on the Languages page under the Settings area.

2

Article ID

Integer ID for this article, e.g. 33578

Edit Article

3

Title

Article Title, text string

Edit Article

4

Created On

Date article first submitted to BDN

None

5

Type

Article type, GetPublished, etc.

Edit Article

Most typically this would be GetPublished; you can see the complete list under Settings at Content Types.

6

Visibility

New-new article
Public-reviewed article

Edit Article

Combines with Status to determine whether an article is published.

7

Status

Draft-waiting to be reviewed
Live-reviewed and accepted
Rejected-reviewed and rejected

Expired-formerly live but no longer

Edit Article

Only Live and Public articles are published for all to see.

8

Preview Article
Hide image
magnifier

Always the magnifying glass

Preview article in a new browser window

9

Delete
Hide image
redx

For Draft Articles the red X; not displayed for Live articles, which cannot be deleted by the author.

Delete the article

Permanent, cannot be undone. Does include a confirmation step.

10

Optional: Publish

Not displayed for most users; must have Editor privs.

Approve/reject/etc. the article in a new browser window.

    My Information

This simple page has three areas:

* Author Information

* Roles

*Articles

Author Information

The Author Information area consists of a form where you can enter and edit your author information: name, email, biography and photo. Currently only the name is published; future plans include the display of the others with the exception of email, which will never be published. When uploading a new image for your author photo we recommend you check the ‘Clear image’ check box. Note that the image will not be resized, so scale your photo to 200x300 pixels before uploading.

Hide image
Click to see full-sized image

Roles

The roles area indicates your role in the BDN editorial process. Unless you are an administrator, this area is display only. Note that the role can vary for different areas, as below. The roles are pretty self explanatory and will not be discussed in this document.

Articles

The bottom area, Articles, is exactly the same as presented on the My Articles page. See the previous section for more details.

    My Tax Forms

This page displays a simple form you use to upload a tax form, and a table with any tax forms previously uploaded. It was discussed earlier in the Submit Tax Form section.

    My Missing Warranties

Last but not least in the My GetPublished area is the Missing Warranties page, which presents a list of any submissions for which you have not completed the Warranty submission process. This was discussed earlier in the section on that step.

    Articles

This section is primarily of interest to bdn Editors and will not be described in this document. It has five pages:

* Manage articles

* Submit Articles

* Edit Articles, and article mappings

* Review Articles

    Authors

Similarly, the authors area, with its page Manage Authors, is the province of BDN Editors and Publishers and thus beyond the scope of this document.

You can edit your own author information via the My Information page under the My GetPublished area.

    Settings

Settings has three pages: these pages are for information only; you cannot change any of them nor take action through them.

* Languages lists the possible values for BDN article languages. If you would like to request support for an additional language (in which you write or translate), contact us via QualityCentral (you can use the “Report a Bug” link at the top of every page to create a new report for GetPublished).

* Content Types lists the available content types. They are presented here for information only. Most GetPublished submissions will use the GetPublished type (it will be the only one available to you and the control will be read only); if your account allows for access to other content types, then the appropriate ones will be displayed on the content type pulldown control of the edit/add article page.

* About is bdn GetPublished About page, with information typical of that kind of page.

    Downloads

This section includes three pages, two for downloading tax forms and the third the Microsoft Word bdn template. These have been discussed in their respective sections.

US residents should use the W9 tax form at http://gp.Borland.com/files/w9.pdf; those outside the USA the W8 at http://gp.Borland.com/files/w8.pdf; all should use the Word template at http://gp.Borland.com/files/bdn.dot.

Server Response from: ETNASC01