doc_open

This function creates a new document tree and returns an identifier that may be used in subsequent calls to current_doc, oid_caret, insert_tag, and other functions. This function also generates an initial context for fragments so that context rules can be turned on for a partial document when displayed in a window using the doc_show command. The arguments that follow are optional.

path — Specifies the path name of a document directory or file name to load the initial contents of the document tree. If not specified or a null string, the document tree is empty.

flags — A bitmask that specifies open options and is constructed using OR with the following flags:

• 0x001 — Open for read only and do not lock the underlying file. If this is not set, the underlying file will be locked if possible and the document will be read-only if no lock was acquired.

• 0x002 — Open for writing and do not lock the underlying file. The document will be modifiable even though the underlying file is not locked. If the document was already open in memory, this will additionally attempt to lock the underlying file.

• 0x004 — Do not lock the underlying file. Overrides all other flags which might acquire a file lock. The resulting document will not be modifiable unless 0x002 is also given.

• 0x008 — Do a completeness check when reading the SGML or XML file. This corresponds to the -cc option for startup and the edit command.

• 0x010 — Do not do a completeness check when reading the SGML or XML file. This corresponds to the -nocc option for startup and the edit command. By default, a completeness check is not done if the file was saved by Arbortext Editor. This bit is ignored if bit 4 is also specified.

• 0x040 — The document type specified by pubid and sysid should be used to parse the SGML or XML file instead of the document type specified in the file itself.

• 0x200 — Open the document without loading a stylesheet. If the document is called later by doc_show, the required stylesheet is loaded at that time.

When an application opens a document without a stylesheet using this flag, a subsequent write or save operation will not load the stylesheet. Without a stylesheet, all original line breaks in the document are preserved during the write or save. If you do not want to preserve the original line breaks, do not specify this flag when opening a document.

• 0x400 — Do not prompt the user if the document type associated with the document does not exist or is not compiled. Instead, return -1.

• 0x8000 — Source the associated document type instance files (instance.acl and instance.js), the document command files (docname.acl and docname.js), and any applications in the custom directory's editinit subdirectory. By default, these files are not processed until the document is displayed in a window with the doc_show function or edit command. The editfilehook is not called by doc_open but only if doc_show or edit is used.

• 0x10000 — Treat the document as if it were created using File > New. In this case, the path name is set to null and the document name is of the form Documentn.

• 0x20000 — Specifies that if an autosave or recovery file exists for the document, the user should be prompted to select the document to open.

• 0x40000 — Specifies that the pubid parameter is actually a namespace URI instead of a public identifier. If the 0x040 bit is also specified, then the namespace URI is used to locate the XML schema to parse the document. The sysid, if given, specifies the path to the DTD/schema file and is used if the namespace URI is null or is not resolved by catalog lookup.

• 0x80000 — Open the document in free form mode, ignoring the document type specified in the file or by the public identifier pubid and system identifier sysid parameters. Flag bit 0x100 (open as XML) is implied by this bit.

• 0x200000 — Specifies that the path name parameter path is actually a string to parse instead of a file to open. If the string does not contain a DOCTYPE declaration, the pubid and or sysid parameters must be given so the desired document type is used to parse the string. Otherwise, the 0x80000 bit must be specified. If the string contains XML markup but does not start with an XML declaration, the 0x100 bit must also be specified.

• 0x1000000 — Do not add the document to the File menu's list of most recently used documents if this document is subsequently opened in an Edit view.

name — Specifies a name to be used for informational purposes. If omitted or null, the base name of path if given is used. If path is omitted, an internal name is assigned.

pubid — Specifies the public identifier for the document type.

sysid — Specifies the system identifier of the document type.

The pubid and sysid arguments specify the document type for the document tree if path is omitted or null or if the associated SGML file does not specify a DOCTYPE declaration, or if bit 0x040 is included in flags. The pubid and sysid arguments are ignored if path specifies an SGML file that starts with a DOCTYPE declaration or a binary document file, unless bit 0x040 is included in flags. As a special case, if pubid is "help", the built-in help window document type is used. If the document type is not specified, is “ascii”, or cannot be determined, then the ascii document type is used.

stylesheet — Specifies the stylesheet to be used instead of the default stylesheet for the document. If bit 0x200 is included in the flags parameter, the stylesheet parameter is ignored. If the specified stylesheet does not exist, Arbortext Editor displays an error message and the function returns a -1.

The document identifier returned should be deleted with the doc_close function when it is no longer needed to unload the document tree from memory.