added 18.07

git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@2049 abb3cda0-5349-4a8f-a601-0c33ac3a8c38

documentation/18.07/eiffelstudio/eiffelstudio-reference/eiffel-information-system/eis-outgoing/index.wiki

@@ -0,0 +1,59 @@
+[[Property:title|EIS: Outgoing]]
+[[Property:weight|2]]
+[[Property:uuid|773ef802-5f9f-107a-4c5d-8dcf17654d23]]
+==Annotations==
+
+Annotations for outgoing EIS links may be applicable to:
+*  An individual class or feature. In this case the annotation appears in the class text, as part of an Eiffel <code>note</code> clause (the obsolete keyword <code>indexing</code> may still be supported, depending upon which syntax level is chosen in project preferences).
+*  A target, library or cluster. In this case the annotation appears in the associated ECF file. 
+
+EiffelStudio provides support for entering annotations through the [[Information Tool|Information Tool]]. 
+
+To specify a link between Eiffel and external information, you include such an annotation. 
+
+The primary components of an annotation are: 
+#  The '''EIS''' marker. 
+#  The '''[[Protocols|protocol]]''', which indicates the type of external information, and making it possible for EIS to determine the associated external tool. If the '''protocol''' is omitted, its value defaults to "URI".
+#  The '''source'''. This is the location of the external information, for example a URL, or a file name. 
+
+==Syntax for Annotations==
+
+Annotations can occur in Eiffel source code and in project configuration files (.ecf). The format of the '''EIS marker''' varies depending upon the context in which it is used. The rest of the annotation format is the same in both contexts.
+
+Individual annotations can be placed in Eiffel files either through the [[Information Tool]] or by manual editing of the files. 
+
+Additionally, a special type of annotation called an '''Automatic annotation''' can be specified for Eiffel configuration [[general target options|targets]]. An automatic annotation on a target will put an implicit annotation with a variable source on each class in the target. An implicit annotation on any particular class can be overridden by an explicitly coded annotation, when necessary.
+
+The following example illustrates the form of an EIS annotation written in Eiffel source code. The annotation appears in the <code>note</code> part of a class or feature definition:
+<code lang="text">
+EIS: "name=Project Requirement", "src=$(system_path)/docs/requirements.pdf", "protocol=PDF", "nameddest=4.1", "tag=requirement"
+</code>
+
+The '''EIS marker''' is the label '''EIS:''' (this label is called the ''Note_name'' in the ISO/ECMA Eiffel Standard syntax). The '''EIS marker''' tells the Eiffel Information System that this particular ''Note_entry'' is of interest to EIS. 
+
+The '''name''' property assigns a name to this annotation. The name will be visible in the [[Information Tool]].
+
+In this example, the '''source''' name (src) includes the string '''$(system_path)''', a reference to a [[Variable Definition|variable]], '''system_path''', which is a predefined variable for the the project location. 
+
+The '''protocol''' is '''PDF'''. 
+
+The '''nameddest''' property (name destination) is a specific property of PDF documents that tells the external tool for PDF documents to open the document at a particular named destination. 
+
+The '''tag''' property associates a text tag, in this case "requirement" with this link. Tags show up in the [[Information Tool]] and can be used to organize annotations. 
+
+The following is an example of an annotation  Eiffel configuration (.ecf) file: 
+
+<code lang="text">
+<note> 
+    <EIS protocol="pdf" name="Project Requirement" src="$(system_path)/docs/requirements.pdf" nameddest="4.1"/>
+</note>
+</code>
+
+Eiffel configuration files have XML definitions, so this is just an XML version of what was coded into an Eiffel class above. The annotation appears in a <code lang="text"><note/></code> element. The '''<code lang="text"><EIS/></code>''' element plays role of '''EIS marker''', just as '''EIS:''' does in the <code>note</code> entry in the source code example above. The '''<code lang="text"><EIS/></code>''' element in Eiffel configuration files is supported in ECF schema version 1.4 and later.
+
+
+{{seealso|<br/>
+[[Variable Definition|Variable Definition]]  }}
+
+
+

documentation/18.07/eiffelstudio/eiffelstudio-reference/eiffel-information-system/eis-outgoing/information-tool/annotation-management.wiki

@@ -0,0 +1,48 @@
+[[Property:title|Annotation Management]]
+[[Property:weight|1]]
+[[Property:uuid|696457ef-ac1f-40c1-a0da-54900d9cccf8]]
+The Information Tool gives you the ability to '''add''', '''modify''', and '''remove''' annotations from within the tool. When you manage annotations via the Information Tool, the appropriate text changes are made to the annotation targets. So, for example, if you use the Information Tool to add an annotation to a class, you will see the annotation after a new '''EIS marker''' in the <code>note</code> part of the class text. 
+
+
+{{note|Annotation management is not available in lists corresponding to tag nodes in the information tree. That is, annotations listed in ''All tags'', ''Items without tag'', and nodes for specific named tags cannot be altered. }}
+
+Of course, you can also use the EiffelStudio editor or an external editor to manage annotations in Eiffel source code and configuration files using the annotation syntax described in [[EIS: Outgoing]]. The advantage to using the Information Tool is that the tool modifies the files for you, making the process less prone to error.
+
+==Adding==
+
+For each node in the information tree, the list of associated annotations is visible to the right. At the bottom the list, there is an entry that is blank, except for the '''Name''' column which contains an ellipsis (" ... "). Double clicking the blank line creates a new unnamed annotation. You can then modify the new entry as you wish.  
+
+==Modifying==
+
+Select a line in the annotation list, then click into a column you wish to change. This will activate ''editing/choosing'' mode. Now you can edit text in the column or if the column is a drop down list, you can choose an alternative entry. Once the editing area drop down list is deactivated, the modification is done and synchronized into code automatically. 
+
+==Removing==
+
+By pressing '''Delete''', or clicking the ''delete'' button [[Image:16x16--general-delete-icon]] on the bottom toolbar, you will delete any selected annotations in the list. This deletes the annotation entries from the list and also from the corresponding the Eiffel class or configuration text.
+
+
+{{note|Multiple entries in the annotation list can be deleted by selecting them all prior to clicking ''delete''. }}
+
+==Enabling and disabling automatic annotation entries==
+
+Automatic annotations can be enabled for a particular project target. Once enabled, each class in the target will exhibit an implicit annotation with a particular source. You can define the source at the same time you enable automatic annotations for a target.
+
+To enable automatic annotations, select the desired target in the information tree. When you do this, the button on the bottom toolbar with the automatic annotation [[Image:automatic annotation icon]] icon becomes enabled. Click this button and you will see the '''Edit Automatic EIS Entry'' dialog box as in Figure 1.
+
+
+[[Image:edit automatic eis entry dialog]]
+
+Figure 1. The Edit Automatic EIS Entry dialog
+
+
+You enable automatic annotations by checking the box labeled '''Enable Auto-Entry'''. You construct an appropriate source from explicit strings and/or variable names in the are labeled '''Source'''. 
+
+You can disable automatic annotation entries on a target by invoking the Edit Automatic EIS Entry dialog box and un-checking the '''Enable Auto-Entry''' checkbox. 
+
+
+{{note|Most changes made to annotations via the Information Tool are irreversible. However, changes made to annotations on a class or feature which is currently open in the Editor Pane may be reversed by using the editor's '''Undo''' command. The '''undo''' feature should be used with caution as the '''undo''' does not function in some early EIS versions.}}
+
+
+
+
+

documentation/18.07/eiffelstudio/eiffelstudio-reference/eiffel-information-system/eis-outgoing/information-tool/browsing-information.wiki

@@ -0,0 +1,73 @@
+[[Property:title|Browsing Information]]
+[[Property:weight|0]]
+[[Property:uuid|2260eabd-cbc9-c385-6295-96474249953f]]
+[[Image:information tool v71|1000px]]  
+
+Figure 1: The Information Tool
+
+
+==Information Tree==
+
+On the left of the tool window is the information tree. The tree displays all locations which contain annotations, as well as a subtree of tags by which annotations can be organized. Clicking or pressing enter on a node of the tree displays the list of annotations associated with that node. In Figure 1, the node APPLICATION, a class, has been selected, and its annotations are listed on the right.
+
+A node in the information tree that has annotations will be decorated with the small "i" icon [[Image:EIS information icon]], as you see in the case of APPLICATION.
+
+You can navigate to the following types of nodes in the information tree:
+*  Target
+*  Cluster
+*  Library
+*  Class
+*  Feature
+*  Items without tags
+
+==Annotation List==
+
+The annotation list appears on the right of the tool window.
+
+The following columns are available in the list:
+*  '''Target''' - the development object where that piece of annotation belongs to. Typical locations are target, cluster, class and feature.
+*  '''Source''' - the address of the resource, typically a URL or file path. Variables can be used.
+*  '''Parameters''' - additional information relevant to certain protocols, for example, a page number in a PDF document.
+*  '''[[Protocols|Protocol]]''' - the type of the Source. 
+*  '''Name''' - the name of the annotation.
+*  '''Tags''' - terms or phrases used to categorize annotations. Tags are separated by '''","'''
+*  '''Override''' - checkbox is checked if an implicit, automatically generated annotation is being overridden by the annotation in this list entry. If this list entry is itself an implicit annotation, this column shows the automatic annotation [[Image:automatic annotation icon]] icon. Override is defined only for  annotations on classes.
+
+
+
+
+{{note|EIS ignores any parameters in '''Parameters''' which are not used by the '''protocol''' specified in the entry. }}
+
+
+{{tip| Clicking on title of each column sorts the list based on the values in that column. }}
+
+
+==Opening Resources==
+
+The most straightforward way of opening a resource from the Information tool is to select the annotation containing the resource and click the "Go to" button on the status bar below the annotation list.
+
+The resource associated with a particular annotation can also be opened by double-clicking on the annotation in the Information Tool list. Alternatively, you can use the arrow keys to highlight the annotation in the Information Tool list and then press enter. EIS opens the resource associated with the annotation using the external tool for the resource's protocol. So, for example, URI resources will be opened in the default web browser.
+
+While using EiffelStudio, pressing '''F1''' while the cursor is in the editor pane will access annotations associated with the Eiffel object that is currently shown in the editor pane. If only one annotation is available, then its resource is automatically opened by EIS. If more than one annotation is available, the '''Select help document''' dialog box (see Figure 2) appears providing the name and type of the available resources. You can use the dialog to choose which resources you wish to display.
+
+
+[[Image:select help document dialog]]
+
+Figure 2: The Select Help Document dialog box
+
+
+==Sweeping Information==
+
+Sweeping annotation information will update the Information Tool with current data for all the annotations in the current system. There are two approaches to sweeping information:
+*  '''Automatic''' - EIS automatically sweeps information at times when Information tool is visible. On the bottom toolbar, clicking the ''automatic sweeping'' toggle button [[Image:automatic sweeping icon]] to the ''down'' position activates automatic sweeping. Clicking the button back to the ''up'' position disables automatic sweeping.
+*  '''Manual''' - Clicking the ''manual sweeping'' button [[Image:manual sweeping icon]] on the bottom toolbar triggers an immediate manual sweep.
+
+The progress bar in the bottom of the tool indicates the progress of a currently executing sweep.
+
+
+==Using Pick-and-Drop with the Information tool==
+
+You can use pick-and-drop with the information tool. If you drop a pebble on the information tree, the annotation list, the "Locate currently edited class/cluster" icon [[Image:EIS locate class or cluster icon]] on the mini-toolbar, or the Info tab [[Image:EIS info tab]], the Information tool will find and display any annotations associated with the dropped pebble. If you drop a pebble on the "Add" button [[Image:EIS add button]] a new entry will be created for the object represented by the pebble. Lastly, dropping a pebble representing a target or cluster on the "Edit EIS auto-node generation property" button [[Image:automatic annotation icon]] will display the automatic node generation dialog for the target or cluster associated with the pebble.
+
+
+

documentation/18.07/eiffelstudio/eiffelstudio-reference/eiffel-information-system/eis-outgoing/information-tool/change-analysis.wiki

@@ -0,0 +1,32 @@
+[[Property:title|Change Analysis]]
+[[Property:weight|0]]
+[[Property:uuid|a503cf13-6374-9932-5ee2-a69b363e6701]]
+[[Image:information tool change analysis]]
+
+The information tool can track changes in an Eiffel system or external resources side, and potentially affected items on either side are listed.
+
+== Major Features ==
+* '''Affected target:''' List of elements of the Eiffel system that would be affected by a change in external resources.
+* '''Affected source:''' List of external resources that might be affected by changes in the Eiffel system.
+* '''Change acknowledgement:''' Acknowledgement of the changes which will be ignored with no further actions.
+
+== Typical Work Flows ==
+
+=== Affected external resources caused by a change in the Eiffel system ===
+# Open a class, add an Information entry with an external resource in the class.
+# Start working on that class, save it at as you normally do on regular basis.
+# Open the information tool, go to Affected source item in the left tree.
+# Check the list of external resources that might be affected by last changes.
+# Acknowledge the changes once you have updated the external resource accordingly (possibly no change is required in the case of simple system changes).
+
+=== Affected items in the Eiffel system caused by an external resource change ===
+# Open a class, add an Information entry with an external resource in the class.
+# Start working on that external resource, save it at as you normally do on regular basis.
+# Open the information tool, go to Affected target in the left tree.
+# Check the list of classes that might be affected by last changes of the external resource. (You may need to click on the "sweep the system now." button to get a full list if auto-sweeping is not enabled.)
+# Acknowledge the changes once you have updated the Eiffel system accordingly (possibly no change is required in the case of a simple edit in the external resource).
+
+== Current limitations ==
+The tracking of external resource changes is limited to external resources that are local files. If an external resource is a URL, it will not detect any potential changes done at that URL.
+
+

documentation/18.07/eiffelstudio/eiffelstudio-reference/eiffel-information-system/eis-outgoing/information-tool/index.wiki

@@ -0,0 +1,10 @@
+[[Property:title|Information Tool]]
+[[Property:weight|0]]
+[[Property:uuid|26e2c799-b48a-c588-cdf1-dd47b1994b09]]
+The Information tool is an EiffelStudio tool that helps you create outgoing annotations in your Eiffel projects. Read more about using the Information tool on the following pages.
+
+
+[[Image:information tool v71|1000px]]
+
+
+

documentation/18.07/eiffelstudio/eiffelstudio-reference/eiffel-information-system/eis-outgoing/information-tool/protocols.wiki

@@ -0,0 +1,21 @@
+[[Property:title|Protocols]]
+[[Property:weight|2]]
+[[Property:uuid|69b4d9d4-570e-e7ac-087b-88449a608d0b]]
+EIS supports following protocols: 
+* URI: This protocol does not need to specified. By default, it will be taken if nothing is specified or unknown protocol is specified.
+
+* PDF: PDF protocol supports three parameters: "type" "page" and "nameddest". (Windows only)
+**  '''type''' - "file" is used to open PDF files in PDF reader. Otherwise in a browser. 
+**  '''page''' - a page number at which to open a document. 
+**  '''nameddest''' - a named destination at which to open a document. 
+
+* DOC: Represents a Microsoft Word document. 
+** '''bookmark''' - Name of a Microsoft Word document bookmark.
+
+The list of currently supported protocols is always available in a drop-down menu associated with entries in the '''Protocol''' column of the [[Browsing information|Information tool]]'s annotation list.
+
+
+{{note|The status of supported protocols described above is as of EiffelStudio version 7.1. }}
+
+
+

documentation/18.07/eiffelstudio/eiffelstudio-reference/eiffel-information-system/eis-outgoing/information-tool/variable-definition.wiki

@@ -0,0 +1,38 @@
+[[Property:title|Variable Definition]]
+[[Property:weight|3]]
+[[Property:uuid|7705ab33-a505-7711-a106-5fedd2e1040e]]
+==Sources of variables==
+
+EIS supports following types of variables which can be used in '''Source''' of annotation list. 
+*  EiffelStudio installation built-in variables 
+** ISE_WIKI = http://dev.eiffel.com 
+** EIFFELROOM = http://www.eiffelroom.com 
+** ISE_DOC = http://docs.eiffel.com  
+** ISE_DOC_UUID = http://doc.eiffel.com/isedoc/uuid  
+** ISE_DOC_REF = http://doc.eiffel.com/isedoc/eis  
+
+*  Other EiffelStudio built-in variables
+**  system_path = The path of the system being annotated
+
+*  Context related built-in variables. These variables can be used in specific context. For instance, '''feature_name''' refers to the name of the feature with which an annotation is associated. 
+**  feature_name 
+**  class_name 
+**  group_name 
+**  target_name 
+
+{{note|A context related built-in variable is only valid in a annotation that is associated with a component to which the variable name refers. For example, '''feature_name''' has no effect if used in a '''target''' component.}}
+
+*  Individual system or library preference variables. This kind of variable is defined in your Project Settings. Manage these variables by following this path in the System tree on the left of the Project Setting dialog:
+<code lang="text">
+	System -> Target -> Advanced -> Variables
+</code>
+
+*  Environment variables. Variables defined in the operating system environment. 
+
+
+==Accessing variables from the Information tool==
+
+When you use the Information tool, the list of all available variables is available through auto-completion when you are typing in an entry under the '''Source''' column of the annotations list. You may either type the dollar-sign '''"$"''' or '''"Ctrl + Space"''' to invoke auto-completion. What you will see in this case is the entire list of available variables, as enumerated above. Bear in mind that this includes all environment variables defined in your operating system environment, which means that some of the entries shown would not be appropriate for use as variables for EIS purposes.
+
+
+