[{"hlpName":"GIT_Exprt","hlpTitle":"Exporting to GIT","hlpText":"All the code listings in the chosen project are sent to a folder whose parent folder (GIT_Xojo) has presumably been set up as a GIT repository. Every database that participates gets it own subfolder (GIT_name of project) in this parent folder (GIT_Xojo).

Normally, the user would simply click on the Send to GIT button.

There are many options in this dialog box but they would seldom be invoked.

Single File, when checked, results in all the methods of the database being combined as a single file before being exported into the (GIT_name of project) folder. This behavior is not generally desired in a GIT repository. The option is provided for a user, familiar with the methodology of GIT, who actually wants this unusual behavior.

It is possible to specify a time/date other than the current time (Now). This would rarely be desirable.

One scenario that might prompt a user to do this would be if you wanted to do a commit in GIT after a particular bit of work was completed so a specific note could be left in the GIT repository. Suppose you worked on functionality A until two days ago and then you started on functionality B. So all the coding before two days ago was dealing with A and the subsequent coding with B. Now suppose in addition that you had not done any exporting and committing to the GIT repository two days ago. Now you regret it because you would have liked to do a commit dealing with all the code of functionality A and comment on it. Click on the Earlier button. You can send the methods to GIT as they existed two days ago by adjusting the time/date parameters. Send the methods to the GIT folder and then use GIT to do the commit. Leave a GIT comment about your work with functionality A.

After doing this, you could return and export the more recent methods to the GIT repository by not changing the time/date parameters and do a second commit which would deal only with functionality B.
"},{"hlpName":"MulMthdEx","hlpTitle":"Export Multiple Code Listings","hlpText":"Under the View menu, the Code Listing item allows the export to text files of the code of individual listings. But there is also a time that it is useful to specify a large group of code listings for which you want to have the code as text files.

The left side of the dialog box allows selection of one or more methods that will be acted upon when clicking on the one of the buttons present on the right side. At least one method has to be selected, otherwise the buttons on the right side are inactive.

Export Simple Text Files
Exports a folder full of simple text files with all the selected code listings as individual files. These can be reviewed in any text editor and simply manually copied and pasted into other projects if desired.

To export all the selected code into a single text file use checkbox One Document. The single text file created will have a table of contents at the beginning. In this way, you could, if you wished, create a single text file that has the most recent version of all your code as one document. It is a form of backup, a source for copy/paste and a place where code can be reviewed.
"},{"hlpName":"RootPref","hlpTitle":"Specifying the Primary Destination Folder (Root Location) - Folder which is the Destination of Exports","hlpText":"ArchiveXojo creates many files. Some of these are simply the text of versions of code. Some are JSON files.

There has to be a designated folder where these files end up. By default, these end up on the Desktop or in subfolders of the Desktop. But you can specify other destinations if you prefer. One built-in alternative is to specify that the exports end up in a folder called _Athenaeum which will be created as a child of the Documents folder. If this option is selected, the exports will end up in this folder or in subfolders of this folder.

If you wish, you can designate any folder to be the primary destination folder (root location). Create the folder using the Finder. Then navigate to that folder and select it by clicking on the Change Custom Folder? button. That folder will now become your primary destination folder. Exported files will end up here or in subfolders of this folder.

It is possible to select some folder that is not simply in the subfolder hierarchy of the Users folder. This is not forbidden, but should be selected only by the advanced user with an understanding of the consequences under different circumstances. There is the potential to cause confusion if at some time in the future, ArchiveXojo is asked to export to this folder, and it cannot find it. Under these circumstances, it will export to the Desktop.

You may find that, although you prefer not to use the Desktop as the primary destination folder (root location), it is still convenient when exporting the text of a single method to have this file end up on the Desktop where it is readily accessible. There is a checkbox, Export Single Method Text to Desktop, that enables this behavior. If that is checked, even though some other folder is the root location, the text files consisting of simply the contents of a single method will end up on the Desktop when exported.
"},{"hlpName":"AMUpdate","hlpTitle":"ArchiveXojo Updates","hlpText":"It is possible that in the future the developer (Bearboat) may provide text files to update the Help files within ArchiveXojo. These text files will be named timestampHelpUpdate.txt (for example 150522HelpUpdate.txt)

Help Files
The situation here is fairly straightforward. There are many windows in ArchiveXojo that have a ? in the left upper corner. When the user clicks on that question mark, a dialog opens with explanatory information about the use of the window. This supplements information provided in the manual and in the text on the window itself.

It is likely that such help files will benefit from additions and modifications in the future, and this provides a mechanism to incorporate such changes into the user's copy of ArchiveXojo.

The user clicks on the Update Help? button and navigates to the new file (timestampHelpUpdate.txt) and selects it to incorporate the changes.
"},{"hlpName":"Unique","hlpTitle":"Code Listings Unique to Project","hlpText":"In this dialog you can choose two projects. There is a left-sided and right-sided pop-up to do this. You are then provided a list of all the methods that exist in the right sided project that do not exist in the left-sided. Occasionally such a thing can be useful. Commonly you would be choosing two projects that were closely related, say one was a rewrite from scratch of the other. You might be curious as to which methods have not yet migrated to the newer version. Here you can see a list. If you wish, you can export to a text file these files or a subset of these files."},{"hlpName":"FndVrsn","hlpTitle":"Find Versions of a Code Listing Known to Have Several","hlpText":"You may find yourself using this function relatively rarely. If you find a code listing using the commonly selected menu item (View>>Code Listing), you can ultimately navigate to a window that shows all the versions of that code listing. But if you know from the get go that you are interested in seeing the versions of a particular code listing, you can come here, (View>>Version), and it is a little faster. Only code listings that have more than one version are shown. When any such code listing is chosen, you are immediately taken to the window that shows all the different versions of that code listing.

The filtering criteria to narrow down the list are identical to those used in View>>Code Listing, here presented in a side panel.
"},{"hlpName":"SnapShot","hlpTitle":"Snapshot of Code in Time","hlpText":"A text file will be created that includes all the code for a project. In general, this will be the code as it exists in the present (Now). That is the default. You might want this as a form of backup or a file that you can use as a reference by doing simple text searches.\r\rUnder unusual circumstances, you might want to produce a text file of the code as it existed some time in the past. This dialog enables the option to choose some time in the past. One potential use might be to create a text file reflecting the state of the project, say a month ago. Create a second text file representing the current state. Using the DIFF editor of your choice, you could then easily compare these two text files and find all the changes in the entire body of code that have been made in the last month."},{"hlpName":"GIT_Loc","hlpTitle":"Location of GIT Repository","hlpText":"The designated GIT folder is something that you generally do not want to change. Set up the folder that you want to use and stick with it. If the user chooses to have a GIT folder, ArchiveXojo will make sure that there is a folder with the name GIT_Xojo at the location specified. At this point, it is just a folder like any other.

Once you have made a decision where you want the GIT_Xojo folder to be, then you have to use GIT utilities to set up that folder as the one that GIT is watching on your local machine. This requires an elementary understanding of how GIT works.

Once this folder has been chosen and set up with your GIT tools, then all the code listings of any project (as text files) are exported to subfolders of this location (one subfolder for each project). This happens whenever the user choses GIT from the Export menu. In this way, GIT can keep track of the changes that have been made between the time of one export and the next.
"},{"hlpName":"AutoNote","hlpTitle":"Automatic Note with Import","hlpText":"If Create Note with Importations is checked, every time that code listing versions are added to the database the user is given an opportunity to create a note. Some users may like to document their progress by being able to create such a note with every import. Some like to organize their code starting and completing discrete sub-projects and only doing an import when such a sub-project is complete. This is akin to the way that GIT works, inviting the user to create a note with every commit.

Others might not find this useful and being continually asked about creating a note simply annoying. Uncheck Create Note with Importations.

It is also possible to create a note on any topic at any time under the View>>Notes menu item.
"},{"hlpName":"AlrtSpeed","hlpTitle":"Alert Dismissal Speed","hlpText":"Many of the alert dialogs in this application will self-dismiss after a time interval. How quickly this occurs can be adjusted here.

There are many alerts or notifications that pop-up during the use of ArchiveXojo. Most of these will self-dismiss themselves saving the user the slight effort of clicking on the Done button. These alert boxes have a countdown in the left lower corner. If you click on this countdown, you will give yourself more time to finish reading the message.

As you become more familiar with the program, the notifications become less and less necessary. Here you can adjust just how long they stay on the screen before self-dismissal. The beginner might find the slow dismissal time to be best while the more experienced user would likely find the fast dismissal to be better.

The alerts are most commonly running in a separate process so the you can just ignore them and continue to work, secure in the knowledge that they will eventually self-dismiss.

Another set of users might just find this whole self-dismissal business to be weird and annoying. There is an option here to turn off self-dismissal all together: uncheck Self-Dismiss Alerts
"},{"hlpName":"FltrMthd","hlpTitle":"Search/Filter Code List","hlpText":"In the top bar are many criteria that can be entered to cut down (filter) the code listings being displayed. This is how you \"search\" for a specific code listing. Once you have filled in some of these filtering criteria, there is no button to \"activate\" the search. Simply wait a couple seconds for the criteria to take effect.

Most of this is straightforward. One little thing is potentially confusing.

If you select from the pop-up Any Project one particular project and the checkbox Most Recent Version is selected, a small checkbox will appear labeled Most Recent in this Project. With a single project selected and Most Recent Version selected, there are actually two different sets of methods that the user might be trying to specify.

1. Only the methods of the specified project that are the most recent version of that code isting across ANY of the projects participating in ArchiveXojo. So if that code listing had a more recent version in some other project, it would NOT show up.

2. The potentially larger set of methods that represent the most recent version in THAT project. They will show even if there is a more recent version of a code listing with this same name in some OTHER project.

Since there are sensible reasons for wanting one or the other outcome under different circumstances, it makes sense to allow the user to choose either one. Selecting the checkbox Most Recent in this Project will activate the search for the second set. Otherwise, the first set will be returned.

Occasionally there is a problem searching for a word in the text of a code listing. Let's say you want to find the Xojo command Sin as in answer = Sin(number). Searching with the string Sin will find this line but it will also find potentially many other lines with the relatively common string Sin such as resin = resin + 1. To indicate that your are interested only in the WORD Sin, surround the string with spaces ( Sin ) when you fill in the Code Contains find search box. That will find the line answer = Sin(number) but will ignore the line resin = resin + 1.

The column headers Code Size and Comment Size refer to the number of characters of code and the number of characters of comment in the particular method.
"},{"hlpName":"CmprVrsn","hlpTitle":"Compare Versions of a Code Listing","hlpText":"Two versions of the code are shown, The older one is to the left; the newer on the right. There is a checkbox, Just Code, which will result in showing only the pure code of the method versions by stripping out all the comments.

The Clipboard buttons place the text of the code onto the Clipboard. They can be activated by the keyboard shortcuts Command-L (old version) and Command-R (new version). These buttons are given keyboard shortcuts to facilitate their actions being incorporated into scripts.

The text of the method versions shown can be exported as text files. Then they can be compared by any DIFF application (such as Kaleidoscope) to find the differences between the two displayed method versions.

There is a small colored circle on the left side of the window and in the center a percentage is displayed. The percentage is an estimate of the degree of similarity of code between the two versions.

A built in DIFF utility is activated by clicking on that circle (the DIFF button). Lines that appear only in one method or the other are shown in orange. When looking for the differences between two method versions, this often suffices, and it is fast and convenient. It does not provide as reliable and sophisticated analysis as is achieved by exporting the text of each version to a full scale third party DIFF application.

The comparison logic of the built-in DIFF utility is modifiable. This can be useful to avoid excessive \"sensitivity\". Normally, the DIFF tool will highlight differences related to capitalization. Sometimes you might want this. At other times it is useful to suppress. This is accomplished by holding down the Shift-key when you click on the DIFF button. Similarly, you can suppress highlighting lines that vary only in the presence of spaces. Hold down the Option(Alt)-key when you click on the DIFF button, and lines that differ only in their internal pattern of spaces (apart from initial spaces) will not be highlighted. Hold down both the Option(Alt)-key and the Command(Ctrl)-key and lines that differ only in their pattern of spaces, be it internally or initially, will not be highlighted.

To minimize sensitivity, hold down all three keys: Shift-key, Option(Alt)-key, and Command(Ctrl)-key.

If you are not interested in differences that relate only to comments, use checkbox, Just Code, so that the code, stripped of all comments, is visible before you run the DIFF evaluation.
"},{"hlpName":"CharWordLine","hlpTitle":"Number of Characters, Words, Lines in Project","hlpText":"1. Select the Project from the popup.
2. Click on the Go button.

Blank lines are not counted as lines.

After clicking on the Go button, which will prepare statistics for the present time, a button, Change Over Time will appear. This will fill-out a listbox of the status of these values over the time of the development of this project. This can take a bit of time; follow the progress in the window title bar.

If you wish, you can then click on the Export as Text Document button which will create a tab-delimited text file of the data in the listbox. You can take this file and analyse it to your heart's content in a spreadsheet or graphing program.

* * * * * * * * * * *

There is plenty of debate as to whether such metrics have any value whatsoever. I will leave that aside. People can make up their own minds.

However, there is a flaw in the methodology of how these calculations are done because of the nature of ArchiveXojo. This may or not be significant, depending on the typical workflow of the programmer. If a user deletes any code listing from a participating project, ArchiveXojo has no knowledge of this and continues to carry its content in its own records. Therefore the code in the deleted method continues to contribute to the totals.

Similarly, if the programmer is in the habit of renaming code, the numbers will become distorted because ArchiveXojo is carrying the code listing under the old name and the new name. Such code will then be counted twice in the methodology employed here.

If the programmer wanted to avoid such distortions, one could go to the effort, when deleting a code listing or renaming a code listing, to leave the old code listing in place with a minimal content (such as one line like - // code removed). Then bring this depleted code into ArchiveXojo before finally deleting it forever. Then ArchiveXojo's last memory of this code listing would be a method with essentially no content.
"},{"hlpName":"Thin","hlpTitle":"Thinning Out Versions","hlpText":"It is not really necessary to delete versions from the ArchiveXojo database, but the user might feel that keeping all the versions, particularly ones that are very similar to one another and arise in the course of debugging a particular peice of code over a short period of time to be clutter.

Thinning deletes some of the code listings from the database using an algorithm that tends to preserve the code versions that exist after a flurry of coding. It preserves only versions separated by the time interval selected. For example, selecting 1 hour will preserve only versions that are separated from one another by at least one hour. This thins out the multitude of versions with minor variations that can accumulate during the active testing and development of a bit of code. The larger the time interval the more methods will be deleted.

To illustrate this graphically, imagine a time line with a I at every point in time that a versions of a particular bit of code was created. Code versions tend to get created in \"spurts\" as a bit of code is being debugged. The below might be an example

II III III II III IIIII III IIIIIIIIII III III

Now image that 1 hour on this timeline is ______ in length. The versions in gray are the ones that would be selected for deletion if the user chose 1 hour as the time interval.

II III III II III IIIII III IIIIIIIIII III III
_____ ______ ______ ______ ______ ______

Now image that 1/2 hour on this timeline is __ in length. The versions in gray are the ones that would be selected for deletion if the user chose 1/2 hour as the time interval.

II III III II III IIIII III IIIIIIIIII III III
__ __ __ __ __ __ __ __ __ __ __

The shorter the time interval, the fewer versions are deleted.
There is a tendency for the last version of any given spurt to be a non-deleted one, if there is a sufficient time lapse between spurts.
"},{"hlpName":"VwOne","hlpTitle":"Method VwOne form","hlpText":"The search field allows highlighting of any string in the code (both with and without the comment). The actual number of \"hits\" is displayed in the upper corner of the text areas. It can vary as it is possible that the code with comments will contain more instances of the given string than the code from which the comments have been stripped.

If you want to search through the text with the previous search string, just push on the Go button with the empty search box. The old value is remembered and will be used. One use for this is to run through a series of code handlers. Click on the Next or Previous button to bring up another piece of code and then simply hit on the Go button again.
"}]