Although packages can contain multiple files of different types and even an internal folder structure, the Developer regards each package as a single document. The file(s) and/or folder(s) within a package are components of the package, rather than Developer documents as such. These facts have implications for how packages function in the Developer and how best to use them. The main considerations for packages are how many items a package should contain, what the items in the package should be named, and whether the package should have an internal folder structure.
Number of Package Items
When creating packages, you need to decide whether each package document should hold a single file or multiple files. Although there is no limit to the number of files and folders you can add to a package, it is generally a good idea to create packages with a single file or a few related files rather than to add all of your external files to one package.
Because the Developer regards each package as a single document, tasks such as publishing and exporting affect an entire package, even if only part of it is needed. For example, when you publish a document that is linked to a file in a package, all of the files in the package are included in the published output, even those files that are not linked to the document being published. This is undesirable, as publishing unused files takes longer and increases the size of the published output.
Nevertheless, there are situations in which you must keep multiple files in a single package. For example, suppose that you want to use a package to link to a custom web site that consists of several linked pages containing graphics (rather than making the site available on a server and linking to it as a URL attachment). To do so, you must copy the entire file and folder structure of the web site into one package for the hyperlinks in the web site to work and the graphics to appear properly.
Naming of Package Items
Each package is a Developer document and, as such, is identified by its Document ID, rather than its name. In contrast, package items are NOT Developer documents and do not have Document IDs. Rather, each package item is identified by the Document ID of the package in which it is stored and its name, as well as its relative path within the folder structure of the package, if relevant (see below). This difference has a number of consequences:
First, if a package contains multiple files and/or folders, the name of each item at a given level of the package must be unique. This is identical to the requirement for folder names (but not document names) in the Library.
Second, when you link to a package attachment, you actually link to a single file within the package, not the overall package document. To uniquely identify the target of such a link, the link path must include the name of the package file, as well as its relative path within the folder structure of the package, if relevant (see below). As a result, if you change either the name or the relative path of the package file, you break the link to it. Therefore, it is recommended that you establish final names for all package items before linking to them.
Warning! The Broken Links tool does not penetrate packages and cannot detect when links to package files are broken.
In contrast, because Developer documents are uniquely identified solely on the basis of Document IDs, a package can be renamed and/or moved within the folder structure of the Library without breaking any links to the files it contains. This is identical to the behavior of all other Developer documents, such as modules, topics, glossaries, and so on.
Warning! It is best to avoid using ampersands "&" or percent signs "%" in a package file name. Document attachment names with those characters may not open depending on the protocol for your security layer for deployed content. Document attachment names with ampersands or percent signs will NOT open if you are using the Knowledge Center to deploy your content.
Internal Structure of a Package
If you do choose to store multiple files in a single package, you might want to organize them using a folder structure within the package. For example, in the case of a custom web site such as that mentioned in Number of Package Items, the package must have an internal folder structure identical to that of the source.
As stated above, when you link to a package file, the link path includes the relative path of the file within the package. It is therefore recommended that you keep the internal package folder structure relatively simple so as to avoid creating excessively long link paths (>255 characters). In addition, if you change the relative path of a package file after linking to it, you break the link. Therefore, it is recommended that you establish the final internal structure of a package before linking to any items it contains.
Warning! The Broken Links tool does not penetrate packages and cannot detect when links to package files are broken.
In summary, when using packages, you should consider the following recommendations: