This chapter describes procedures that can be followed to create an amendment to the eAIP. These procedures are not mandatory and other procedures can very well be designed, notably to adapt to local needs.
- Inserted and Deleted Elements
An "inserted element" is an XML element from the eAIP DTD whose Updated attribute has the value "Inserted" for a given AMDT. A "deleted element" is an XML element from the eAIP DTD whose Updated attribute has the value "Deleted" for a given AMDT.
Most elements have an Updated attribute, whose possible values are "Inserted", "Deleted" and "No" (which means the element is not updated in the current AMDT). See the eAIP DTD Documentation for details about a specific element. There is an element named Inserted, whose Updated attribute is always "Inserted". Similarly, there is an element named Deleted, whose Updated attribute is always "Deleted".
- To fix an amendment
To apply definitively the changes of an amendment into an eAIP by removing all deleted elements (including their content) and by the removing inserted elements (their content remains). An XSLT-based solution that implements this transformation is provided by EUROCONTROL, in the tools/Amendments directory of the eAIP package.
In this document, we use the following notation to identify AMDTs.
eAIPa : complete eAIP containing the fixed changes of Amendment "a";
AMDTb : mark-up of the changes of Amendment "b";
eAIPa+AMDTb : complete eAIP containing both the fixed changes of "a" and the marked-up changes of "b";
eAIPab : complete eAIP containing the fixed changes of both "a" and "b";
The effective-date of an amendment is expressed by the letter "a", "b", etc.: "a" is effective before "b", and so on.
As defined by the eAIP Specification, an eAIP document is valid if it validates (in the XML sense) against an official eAIP DTD (preferably the latest published version of the eAIP DTD) and it follows the "additional rules". Please refer to the eAIP Specification for more details.
For the sake of this document, we define the expression "amendment-valid": an eAIP document (presumed to contain at least one amendment) is "amendment-valid" if:
It is a valid eAIP and
It is still valid after the amendment mark-up it contains has been fixed and
Already published amendments1 are still "amendment-valid" with this new amendment.
Since this is a recursive definition, we need to add a simple rule:
A valid eAIP without amendment mark-up is amendment-valid.
Why these three rules? Consider the following example. Let's say we have 3 amendments:
eAIPa+AMDTb: effective since 2 weeks
eAIPab+AMDTd: AIRAC amendment effective in 2 weeks
eAIPab+AMDTc: non-AIRAC amendment we want to publish today, effective immediately
Let's say there is a textual reference and a link like this: "See paragraph ENR-1.3.4". What would happen if, as part of AMDTc, we have deleted that paragraph? The validation process will not spot this because that paragraph is still in the document, even though it is marked as deleted. In fact, we want it to stay in the document, so that we can show it as deleted in the HTML version of eAIPab+AMDTc. Moreover, it is still valid to have references to that paragraph, as long as these references are themselves marked as deleted as well.
So the solution is to validate the document first with the amendment mark-up (eAIPab+AMDTc), to be sure that we publish a valid eAIP. After that, we fix AMDTc into eAIPab to remove all deleted content (the result is eAIPabc) and we validate it again. At this point, if any non-deleted content makes reference to deleted content, eAIPabc will not be valid. This is an example of a situation where eAIPab+AMDTc does not comply to the 2nd point of our definition. This is not acceptable and thus the rule has been created.
Let's say that, as part of AMDTc, we insert a textual reference and a link like this: "See navaid DON". What would happen if, as part of AIRAC AMDTd, this time, we remove that navaid? As in the first case, the normal validation process will not complain. This is quite logical, because our reference to that navaid is not broken. Indeed, in eAIPab+AMDTc, the navaid is not marked as deleted (the navaid will only be deleted in 2 weeks). Even a validation of eAIPabc will not help.
The solution is to copy AMDTc to a clone of eAIPab+AMDTd and "amendment-validate" it. That is, we have to validate:
eAIPab+AMDTd+AMDTc
eAIPabc+AMDTd
eAIPabcd
Arguably, these are exceptional cases. Why would one insert a reference to a navaid that will be removed 2 weeks later? Nevertheless, we must ensure that any published eAIP is a valid one, and an "amendment-valid" one, for that matter. We propose the procedures below for that purpose.
We suppose that we already have published eAIPa (already effective), eAIPc (AIRAC, not yet effective) and eAIPd (AIRAC, not yet effective) and that they are all amendment-valid. We want to create and publish eAIPb, effective immediately.
Copy eAIPa to a new directory to create a draft AIPa+AMDTb
Create a new Amendment element (normally in GEN-0.2), with a unique id (say, "AMDT-2003-01")
Make the changes (see below, manual amendment editing)
Validate the draft eAIPa+AMDTb and correct errors
Make a copy of the draft; fix AMDTb in it to generate eAIPab
Validate eAIPab; if there are any errors, correct them in the draft (back to step 3) and not in eAIPab
For each published but not yet effective amendment (normally only AIRAC amendments) eAIPa+AMDTx (where x > b):
Copy AMDTb into a copy of eAIPa+AMDTx
Validate the resulting eAIPa+AMDTx+AMDTb; if there are errors, correct them in the draft (back to step 3)
Fix AMDTb
Validate the resulting eAIPab+AMDTx; if there are errors, correct them in the draft (back to step 3)
Fix AMDTx
Validate the resulting eAIPabx; if there are errors, correct them in the draft (back to step 3)
Publish eAIPab+AMDTx: it is a corrected version of amendment x
Publish eAIPa+AMDTb
Note
The step numbers above refer to box numbers in the diagram.
There are 2 boxes numbered "7" in the diagram, because they correspond to the same point 7 in the description above (the one in the bottom is not strictly necessary but makes the diagram clearer).
Action number 7.1 is not trivial: it consists in copying all inserted and deleted elements (including their content) to the target, at the right place. If done manually, this means repeating on document eAIPa+AMDTx the changes made on eAIPa at point 3.
In some cases, the first iteration of the point 7 above (i.e. for the first published but not yet effective amendment), together with points 5 and 6 can be simplified by editing that previous amendment version directly and "reversing" the previous amendment mark-up to validate AMDT 1 as in point 5.
This alternative must not be used if there has been any change in that previous amendment that was not part of the amendment. Such changes include sub-sections and paragraphs numbering, styling (classes) and other attributes, and changes in supplements, supplement references and other elements that may be changed outside the scope of an amendment.
The reverse.xslt style sheet is provided for this purpose but should be used with caution (please make sure that you clearly understand the consequences).
Before modifying anything in an eAIP, an editor must consider if the modification is part of an amendment or not. If it is, then the following procedure applies. Note that the eAIP DTD Documentation contains specific amendment instructions for each element.
For text and inline elements amendments (changes inside a paragraph, inside a list item, etc.):
Make the changes:
Insertion: Insert an e:Inserted element and type the new text inside;
Deletion: Enclose the old text inside an e:Deleted element;
Change: Enclose the old text inside an e:Deleted element; insert 2 an e:Inserted element and type the new text inside;
Set the Updated-ref attribute of the e:Inserted and/or e:Deleted element to "AMDT-2003-01".
For elements amendments (new paragraph, deleted item in a list, etc.):
Make the changes:
Insertion: Insert the new element and set its Updated attribute to "Inserted";
Deletion: set the element's Updated attribute to "Deleted";
Change: copy the element; set the original's or the copy's2 Updated attribute to "Inserted" and the other's to "Deleted"; change the deleted or the inserted element's id attribute;
Set the Updated-ref attribute of the inserted and/or deleted element to "AMDT-2003-01".
For attribute amendments (changes to a Ref attribute, etc.), consider that the element itself is changed, not simply the attribute.
Note
2 In general, it does not matter which of the deleted or inserted element comes first in the eAIP document. Anyway, deleted elements are not visible on the paper version and the HTML version makes it clear which one is which. However, there are some cases where it matters: see x:li, e:Sub-section and x:div elements.
The following procedure must be followed to produce a paper version of an eAIP.
Following the suggested directory structure for the eAIP, let's say that we have the previous amendment is in the directory "AIRAC-2003-01" while the new one is in the directory "AMDT-2003-02". Under each of these 2 directories, we notably have the following directories:
eAIP for the XML format;
fixed for the fixed version of the AMDT in XML, FO and AT format;
with-amdt-info for FO and AT files with amendment information;
without-amdt-info for FO and AT files without amendment information;
publish for AT files used to produce PDF files to publish;
publish-amdt for AT files used to produce the "PDF paper amendment", which contains only the changed pages, just like a real amendment;
pdf for PDF files to publish.
The commands below are started from the "AMDT-2003-02" directory. We suppose that AMDT-2003-02 is effective after AIRAC-2003-01.
Note
Currently, only RenderX's XEP XSL-FO rendering software is supported for this procedure.
Generate the new AIP with Amendement information
In FO (in fo/): makeaip sections -d eAIP -t with-amdt-info -f fo
In AT (in fo/): makeaip sections -s with-amdt-info -t with-amdt-info -f at Follow the special procedure for 0.6 sections (tables of contents) (not including the PDF generation, of course, which is not needed here).
Generate the new AIP without Amendement information
In FO (in fo/): makeaip sections -d eAIP -t without-amdt-info -f fo -a false
In AT (in fo/): makeaip sections -s without-amdt-info -t without-amdt-info -f at -a false As for step 1, special procedure for 0.6 sections.
Compare the new AIP without AMDT info to the previous AIP without AMDT info, to create the (soon to be) published version of new AIP (all this in AT format):
For non-differing pages, copy the corresponding page from the fixed version of the previous AIP;
For differing pages, copy the corresponding page from the new AIP with AMDT info; copy them also to a separate "paper AMDT" AT file;
Note
If there is no previous AIP (because the new AIP is the first version of a new edition), then the published version is the same as the new AIP with AMDT info.
Commands using makeaip:
all pages: makeaip amdt_pages -s without-amdt-info -t publish -old-clean ../../AIRAC-2003-01/without-amdt-info -old-publish ../../AIRAC-2003-01/fixed -new-publish ../with-amdt-info -a false
only changed pages: makeaip amdt_pages -s without-amdt-info -t publish-amdt -old-clean ../../AIRAC-2003-01/without-amdt-info -old-publish ../../AIRAC-2003-01/fixed -new-publish ../with-amdt-info -a true
Note
For the "amdt_pages" command, parameters -s and -t are directory paths following the operating system's syntax, while parameters -old-clean, -old-publish and -new-publish are directory URIs, relative to the directory specified by parameter -s.
Generate GEN 0.4 in AT format using the (soon to be) published version of the new AIP; do this at least twice: see the special procedure for GEN 0.4 production for more details:
makeaip checklist -d eAIP -f fo -s ../publish -t publish (note that for the "checklist" command, the "-s" parameter is an URI relative to parameter -d, not a path!)
makeaip GEN-0.4 -d eAIP -f at -s publish -t publish
Gather all pages of the "paper amendment" in a single file; there is currently no command to do this with MakeAIP.bat, so here are the 2 java commands to run successively: java -jar tools\saxon\saxon.jar -o publish-amdt\EC-GEN-amdt-en-GB.at eAIP\EC-eAIP-en-GB.xml tools\Amendments\amdt-only.xslt ATDIR=../publish-amdt java -jar tools\saxon\saxon.jar -o published-amdt\EC-GEN-amdt-en-GB.at published-amdt\EC-GEN-amdt-en-GB.at tools\Amendments\amdt-only-postprocess.xslt
Note
Adapt file names according to your eAIP;
The result is placed into a file named GEN-amdt because of a limitation of MakeAIP, to make the next commands easier;
The ATDIR parameter needs a directory URI.
amdt-only.xslt copies both the recto and verso when either is amended.
Generate the (soon to be) published version of the new amendment and the "paper AMDT" in PDF and publish them:
makeaip sections -f pdf -s publish -t pdf
makeaip GEN-amdt -f pdf -s publish-amdt -t pdf
Perhaps rename EC-GEN-amdt-en-GB.pdf to something more appropriate, since it contains all amended pages, not just those from GEN.
Note
The URIs above are used in XSLT's document() function, so they must not be like a Windows path but must instead respect XSLT URI syntax: the directory separator must be "/" (forward slash, not backslash) and in this specific case they must be relative URIs without URI scheme ("file:", for example). An example of such URI is: "../directory".
You should delete PDF files of NIL sections: they are not used and should not be published.
In the context of paper AIP amendments, only changed pages are sent to AIP subscribers. Consequently, after a few years of operations, a subscriber's copy of an AIP will be composed of pages coming from various AMDTs, each with their set of change bars and insertion/deletion arrows (collectively, AMDT indications). Depending on the AIP production system used by the editor, a new subscriber might receive a complete AIP with all AMDT indications from the past, or with only the latest indications, or even with none at all.
In the context of the EUROCONTROL eAIP, the whole AIP is published for each AMDT and made available on digital media. So a question arise: Should eAIPs be published with or without past change bars?
It is possible that only the latest AMDT indications are made visible in all eAIP formats (XML, HTML, PDF, etc.). Some states might choose to show both an AIRAC and non-AIRAC AMDT in HTML only, when these AMDTs are published together.
There are a few arguments against keeping past change bars:
It is likely that some AMDT indications from a given AMDT get replaced by a later AMDT occurring on common pages, leading to inconsistent indications. One cannot reliably expect to find all indications from a past AMDT;
Past indications attract readers' attention, even to old, well-known changes, while the objective of AMDT indications is to attract attention to the latest changes;
In interactive formats such as HTML, it would be impractical to show all past changes, so it would be inconsistent to have them in PDF and not in HTML.
An argument in favour of keeping past indications is that not keeping them would make published eAIPs different to paper AIPs that users keep in their library. But in fact, the actual information is the same anyway; only the AMDT indications are removed.
Additionally, past indications can still be seen in previous AMDTs, which can be made available on AIS Web sites, on previous CD-ROMs, or kept in a local archive.
If some editors still want to keep past indications, the paper AIP publication procedure above must be slightly modified: at step 3, the non-differing pages should be taken from the previous published eAIP instead of the previous fixed eAIP. The decision whether to keep them or not should be taken from the start, because it would be difficult to generate an eAIP in PDF with all past indications if they were not kept from the beginning.
In certain conditions, paper amendments can lead to "unexpected" results. These are not specific to the electronic AIP, but the eAIP might make them more obvious.
Suppose that we have 2 AMDTs, an AIRAC and a non-AIRAC, and that the AIRAC one is published before but is effective after the non-AIRAC one. The procedure tells us that we need to apply the non-AIRAC changes to the AIRAC AMDT and publish a "corrected" version of the complete eAIP, containing both the AIRAC and non-AIRAC AMDTs.
What can happen is that the non-AIRAC changes (say, a few words inserted somewhere) push the text on the page. Now, if the pushed text propagates until an AIRAC change, we will potentially have a very different AIRAC AMDT. It is normal: we simply have to issue a "corrected" AIRAC AMDT. We need to explain to our AIP readers that this corrected AIRAC AMDT is different by presentation only and not by content. We need to publish on CD-ROM and on our Web site the corrected files, in HTML and PDF.
We can send the corrected paper AMDT either immediately, with the non-AIRAC AMDT, or, at the latest, 2 weeks before the relevant AIRAC date, so that paper users can replace the right pages. Paper users should take care not to mix the pages they have received, because they might very well receive pages with the same AIRAC effective date, but with different content. The latest correction is the only valid one.
In the same conditions as above (2 AMDTs, AIRAC one published before but effective after non-AIRAC one), suppose that both AMDTs are pushing some text in the same section, and that, because of this, they both contain a page without any actual change beyond the pushed text. For example, a paragraph from the previous page was pushed on this page.
The AIRAC AMDT is published and contains this page with its AIRAC effective date. The non-AIRAC AMDT, which we are about to publish, also contains this page, but with its own non-AIRAC effective date. Until now, nothing abnormal: paper users will replace this page by the non-AIRAC one first, and then later by the AIRAC one (possibly corrected).
Now suppose that, when "correcting" the AIRAC AMDT by applying the non-AIRAC changes, we find there is enough white space in the bottom of the previous page to accommodate for the newly arrived paragraph. In other words, each AMDT separately pushed a paragraph to this page, but both AMDTs combined still push only one paragraph, not two. Yet another way to say it is that the non-AIRAC AMDT modifies this page, but the AIRAC AMDT, which is effective after, does not further modify our page. This can happen because of proper management of page breaks, white-space and widow/orphan lines.
What do we see then? The corrected AIRAC AMDT does not contain our page! We can also see that the complete eAIP with the corrected AIRAC AMDT contains this page with the non-AIRAC effective date!
Here again, it is normal: the page is simply deleted from the AIRAC AMDT. We need to attract our users' attention to this fact, so that there is no confusion about this deleted page, since it was previously sent.
A page is part of an AMDT despite not being changed, apparently. The effective date and AMDT number are different, but there is no change bar and the same text is exactly at the same place (no text was pushed). So why is it part of the AMDT?
It happens when the page contains a link to another page, the latter being modified (either there is an AMDT on the target page or its content has been pushed by a change a preceding page): The link target is not at the same place as before the AMDT, so the PDF encoding of the link is different and the page has been found different by the eAIP comparison process.
What can we do about it? Nothing: This page should be part of the PDF files, both the complete eAIP in PDF and the amended-pages-only PDF file, because the link is used in PDF and only the amended version will work within its AMDT. On paper, there is no difference except for the effective date, but the page should be sent anyway for consistency between electronic and paper versions.
Amendment production can be partially automated. For example, provided a content management and versioning software is available, the amendment creation, validation and publication procedure can be completely automatic.
Similarly, if automation is available within the XML editor software, the actual creation and manipulation of changes can be made a lot simpler.
Another approach is a fully automated amendment edition. In this approach, editors simply amend their eAIP without worrying at all about amendment mark-up. They just replace text where needed, add and remove paragraphs here and there, etc. When they have finished, a software program compares the new, modified eAIP with the previous one and insert amendment mark-up where needed. After that, the editors can check the result on screen and on paper.
We expect the industry to provide, in the near future, software tools which will implement these procedures or similar ones, in a user-friendly and yet safe way.