Convert Hyperlinks

FM Hypertext Conversion ©MJH 2023

(File modified: July 29, 2024 4:51 pm)
This site works better with Javascript enabled.
Michael J. Hannah, Los Ranchos, NM.

I produce web pages from documents created with the Adobe® FrameMaker 2019® desktop publishing software (abbreviated throughout my documents as FM). A companion document describes the details of entering hypertext in an FM document. FM provides a checkbox option on the pop-up window to insert a Hypertext command whics is labeled “Validate Command upon Insertion”. If checked FM gives a warning message about any invalid parameters. In all of these warning cases FM leaves the hypertext parameters as entered, and converts that parameter as shown in the examples below, many of which produce errors.

The following examples provide the results of all the link text I think I am likely to enter in an FM “gotolink” hypertext command. As a result of these tests showing what does and does not convert appropriately and ensure avoiding errors, I have documented in the above mentioned document the self-imposed data entry standards I use to limit the type of data I enter in these commands.

to avoid unnecessary complexity I follow a strict data entry practice for the parameters of the few FM hypertext commands I use. These are documented

If there is no “:linkname” included at the end of the parameter to the hyperlink command, FM assumes the entire entry (without a colon) is a linkname within this document, even if it is clearly an existing filename. The warning message is in the format of:

‘{the current document complete pathname}’ does not yet contain the named destination '{the entered parameter}’

If the parameter is simply a linkname to within this document (which does not require a leading colon), or a filename:linkname to some other FM document, this warning message may occur for a legitimate but ignorable reason. It is usually caused by including this hypertext link to a linkname you simply have not yet entered in this (or some other) document but plan to do so. In this case this hypertext link will work unchanged as soon as you enter the specified target linkname, which is why you can ignore the warning.

Including only a trailing colon on the parameter with no following linkname text gives the warning message “Invalid hypertext command: some parameters are missing.” This should always be considered an error.

Note: The Perl script as currently written will only accept a converted Hyperlink with a maximum of two separator slashes in the HREF. Thus sibling and grandchild are the most complex it can handle.

Hypertext entry of just this document’s filename with no linkname assumes the parameter is a linkname to this document, and gives warning of no such link in this document. Resulting converted Hyperlink is an ERROR.

The hypertext entry with this document’s filename and linkname converts unchanged.

The hypertext entry with a leading path to “this” folder and this document’s filename and linkname converts as expected but removes the leading pathname text to this folder.

The conversion of a hypertext entry with a linkname leading colon gives warning of no such link in this document. Conversion does automatically insert this document’s filename, however the resulting converted Hyperlink is an ERROR.

The conversion of a hypertext entry with only a linkname (and no leading colon) automatically inserts this document’s filename resulting in a working link.

Conversion of the hypertext entry of a file in this folder with no leading path to this folder or a linkname assumes the parameter is a linkname to this document, and gives warning of no such link in this document. Resulting converted Hyperlink is an ERROR.

However a hypertext entry of the filename but no leading path to this folder but with linkname converts as expected with no leading path included.

But a hypertext entry with leading pathname text to this folder and fillename and with linkname converts as expected but removes the leading pathname text to this folder.

Note that a hypertext entry without leading pathname text in front of the sibling folder name to indicate a relative location to that parent folder automatically will be assumed to be a link to a child folder, not a sibling, as noted below.

The hypertext entry of a file in a sibling folder with leading pathname text to the parent for the sibling folder but no linkname assumes the entire parameter is a linkname to this document, and gives warning of no such link in this document. Resulting converted Hyperlink is an ERROR.

and likewise the conversion of a hypertext entry with leading pathname text to the parent for the sibling folder but only a trailing colon to close the filename assumes the parameter is a missing linkname to this document, and gives warning of “missing parameter”. Resulting converted Hyperlink removes the entire entered parameter and is an ERROR.

But a hypertext entry with leading pathname text to the parent for the sibling folder, filename and linkname converts as expected and retains the leading pathname text to the sibling.

The hypertext entry of a file in the parent folder with the leading anonymous relative pathname text to the parent but no linkname assumes the parameter is a linkname to this document, and gives warning of no such link in this document. Resulting converted Hyperlink is an ERROR.

and likewise the conversion of a hypertext entry with the leading anonymous relative pathname text to the parent but only a trailing colon to close the filename assumes the parameter is a missing linkname to this document, and gives warning of “missing parameter”. Resulting converted Hyperlink removes the entire entered parameter and is an ERROR.

But a hypertext entry with the leading anonymous relativepathname text to the parent with filename and linkname converts as expected and retains the leading anonymous relative pathname text to the parent.

The conversion of a hypertext entry to a file in a child folder with only the child folder name as path but no linkname assumes the parameter is a linkname to this document, and gives warning of no such link in this document. Resulting converted Hyperlink is an ERROR.

and likewise the conversion of a hypertext entry with leading pathname text to this folder for the child folder name but no linkname assumes the entire parameter is a linkname to this document, and gives warning of no such link in this document. Resulting converted Hyperlink is an ERROR.

Further the conversion of a hypertext entry with leading pathname text to this folder for the child folder but only a trailing colon to close the filename assumes the linkname parameter is a missing linkname to this document, and gives warning of “missing parameter”. Resulting converted Hyperlink removes the entire entered parameter and is an ERROR.

But a hypertext entry with leading pathname text to this folder for the child folder and then filename and linkname converts as expected but removes the leading pathname text to this folder before the child folder name.

And a hypertext entry with no leading pathname text to this folder for the child folder but with filename and linkname converts as expected with no leading pathname text.

These are the most complex links which the Perl program is programmed to handle. Like a link to a child folder above, the above two examples are the only two formats which will work, and like above the optional leading pathname text to this folder in the FM link is removed by the FM conversion.

The results reported in this document were tested by converting documents to HTML with FrameMaker 2019® using basic mode. I do not warrant in any way that this document is accurate or useful, or the results would be the same in another mode or version of FM, and any use of it is at the user’s own risk.

As described in a separate document, this document was composed with Adobe® FrameMaker 2019®, converted using its hyperlink and "Save as HTML" features, post-processed with my custom Perl© script, linked to my Responsive CSS file, and the HTML and CSS are W3C validated.