Automated documentation
The AutoDocumentation feature of XLSior provides a simple way of making self-documenting workbooks. While the documentation is not complete (for obvious reasons it can't automatically update explanations and instructions) it does provide a useful core of necessary information.
The following workbook information can be documented automatically:
- Sheets, including worksheets, chart sheets, macro sheets and dialog sheets
- Names, including Names that are local to worksheets, and Names that refer to formulae
- Cell comments
- External links to other workbooks.
- Advanced techniques used on worksheets.
Each set of AutoDocumentation is stored on a separate worksheet in the workbook, called X~Sheets, X~Names, X~Comments, X~Links, and X~Techniques respectively. There may also be a summary sheet called X~Summary.
These sheets are automatically protected, and cannot be unprotected by the user.
The AutoDocumentation can be inserted and updated manually, through the commands on the XLSior menu, or automatically, through user and workbook preferences. The list of sheets on X~Sheets is also updated automatically when you use a number of other XLSior commands, such as those that insert sheets or change protection or visibility. The summary sheet is updated whenever any of the other AutoDocumention sheets is updated, or when the tests are run.
The AutoDocumentation comands cannot be used on a shared workbook. New AutoDocumentation sheets cannot be added to a workbook whose structure is protected.
The AutoDocumentation sheets use the workbook's current name. If they are being updated automatically as the workbook is saved, they will not show the correct workbook name if:
- You are saving the workbook using the File > Save As... command
- This is the first time you are saving the workbook
In these circumstances you should update the AutoDocumentation again after saving the workbook.
Progress indicator
The listing operations may take a long time for large workbooks. In this case, a progress indicator will appear, showing how many items there are to be listed. The indicator has a Cancel button, which can be used to abort the operation.
There are three phases to a listing operation, each of which shows on the progress indicator:
- Processing the items one at a time. Pressing the Cancel button during this phase will abort the whole operation; the list sheet will not have changed.
- Writing all the items to the list sheet. This happens in a single, possibly long, step, during which the progress indicator does not change. You cannot cancel during this phase.
- Finalising the items one at a time. This usually involves putting in the relevant hyperlinks. Pressing the Cancel button during this phase will stop the finalisation process, but will not abort the whole operation. The list sheet will be updated, but some hyperlinks will be missing. Some of the information about the XLSior sheets may also be inaccurate.
Manual operation
The menu XLSior > AutoDocument has the following commands:
- Update Lists
- Updates any existing AutoDocumentation sheets. No new sheets are added.
- List Sheets
- Updates sheet X~Sheets if it exists, or adds it if it does not.
- List Names
- Updates sheet X~Names if it exists, or adds it if it does not.
- List cell Comments
- Updates sheet X~Comments if it exists, or adds it if it does not.
- List external Links
- Updates sheet X~Links if it exists, or adds it if it does not.
- List advanced Techniques
- Updates sheet X~Techniques if it exists, or adds it if it does not.
- List All
- Updates any of the sheets that exist, and adds those that do not.
- Add Summary sheet
- Adds sheet X~Summary to the workbook if one does not exist already.
