<?php                                                                                                                          require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/app.class.php");    require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/nav.class.php");     require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/menu.class.php");     $App     = new App();    $Nav    = new Nav();    $Menu     = new Menu();        include($App->getProjectCommon());    # All on the same line to unclutter the user's desktop'

    $pageTitle       = "Refactoring in Photran";
    $pageKeywords    = "photran, refactoring, restructuring";
    $pageAuthor      = "Jeffrey Overbey";
    
    # Paste your HTML content between the EOHTML markers!    
    $html = <<<EOHTML

<div id="maincontent">
  <div id="midcolumn">
    <h1>$pageTitle</h1>
    
    <div class="homeitem3col">
      <h3>Analysis &amp; Refactoring</h3>
      <p>Photran 4.0 is the first release to incorporate basic refactoring support
      as well as program analysis-based features such as content assist,
      a Fortran Declaration view, and an Open Declaration action.
      Currently, only two refactorings are supported, but more are in development.</p>
      
      <p><i>The instructions on this page are for Photran 4.0 Beta 4.</i>
      The instructions for prior versions were slightly different.</p>

      <h4>On this page...</h4>
      <ol>
        <li><a href="#prep">Preparing to Use Analysis Features and Refactoring Support</a></li>
        <li><a href="#general">General Instructions for Using Refactorings</a></li>
        <li><a href="#rename">The Rename Refactoring</a></li>
        <li><a href="#introimplicit">The Introduce Implicit None Refactoring</a></li>
      </ol>
    </div>

    <div class="homeitem3col">
      <a name="prep"></a><h3>Preparing to Use Analysis Features and Refactoring Support</h3>
      <h2>Setting Up the Indexer</h2>
      <p>In order to perform refactorings or to use the Open Declaration action,
      content assist, or the Fortran Declaration view,
      Photran must keep track of what modules, subprograms, etc.
      are declared in every file in your project.  This information is updated every time you save a
      file.  Since this part of Photran is <i>experimental</i> and has not been optimized for speed,
      it is disabled unless you explicitly enable it in your project.</p>
      <ol>
        <li> Right-click on your project's folder in the Fortran Projects view
        <li> Click on Properties
        <li> Expand Fortran General in the list on the left, and click on Analysis/Refactoring
        <li> Check the &quot;Enable Fortran analysis/refactoring&quot; check box
        <li> If you want to enable content assist or the Fortran Declaration view,
             check those boxes as well
        <li> Click OK
      </ol>
      
      <h2>Setting Up Module and Include Paths</h2>
      <p>If your source code contains INCLUDE lines, or USE lines referencing modules in other files,
      Photran needs to know where to look in order to find these.  <i>It will not figure this out
      automatically.</i>  For each project in which you plan to use refactoring support,</p>
      <ol>
        <li> Right-click on your project's folder in the Fortran Projects view
        <li> Click on Properties
        <li> Expand Fortran General in the list on the left, and click on Analysis/Refactoring
        <li> List the folders in which Photran should search for INCLUDE files and modules when
             refactoring.  They will be searched in order from the first folder listed to the last.
             Subfolders are <i>not</i> searched automatically; you must include them explicitly.
        <li> Click OK
      </ol>
    </div>

    <div class="homeitem3col">
      <a name="general"></a><h3>General Instructions for Using Refactorings</h3>
      <p>
      In the Fortran editor (for free-format source code), select (highlight) the name of
      a variable, subprogram, etc.  Then right-click on the selected name,
      choose Refactoring from the context menu, and click
      on the name of the appropriate refactoring.
      Enter any information requested, then click Preview to see what changes it will make.
      It is important to verify that they are what you expect!  Then click OK to make the changes,
      or Cancel to avoid making any changes.
      </p>
      <p>
      Where you click on is extremely important.  Consider this program, for example.
      </p>
      <p>
      <tt>
         <small>1</small> <font color="green">! Print hello to the screen</font><br>
         <small>2</small> <font color="#800080">program</font> p<br>
         <small>3</small> &nbsp;&nbsp;&nbsp;&nbsp;<font color="#800080">character</font>(len=*) :: hello = <font color="blue">'hello'</font><br>
         <small>4</small> &nbsp;&nbsp;&nbsp;&nbsp;<font color="#800080">print</font> *, hello<br>
         <small>5</small> <font color="#800080">contains</font><br>
         <small>6</small> &nbsp;&nbsp;&nbsp;&nbsp;<font color="#800080">subroutine s</font><br>
         <small>7</small> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<font color="#800080">character</font>(len=*) :: hello = <font color="blue">'This is a different hello'</font><br>
         <small>8</small> &nbsp;&nbsp;&nbsp;&nbsp;<font color="#800080">end subroutine</font><br>
         <small>9</small> <font color="#800080">end program</font><br>
      </tt>
      </p>
      <p>
      If you click on <tt>hello</tt> in the comment or the string literal (lines 1 and 3), the refactoring will not work, because
      <tt>hello</tt> is not a variable in that context; it is just a piece of text.  If you click on the <i>variable</i> <tt>hello</tt>
      in lines 3 or 4, refactoring will succeed.  Note, however, that the variable <tt>hello</tt> in line 7 is completely different.
      So if you rename the occurrence of <tt>hello</tt> on line 3 and 4, those occurrences will both change, but the <tt>hello</tt>
      variable on line 7 will remain the same.  Similarly, you can rename <tt>hello</tt> on line 7 without changing the variable on
      lines 3 and 4.
      </p>
    </div>
      
    <div class="homeitem3col">
      <a name="rename"></a><h3>The Rename Refactoring</h3>
      <ul>
        <li><b>Purpose:</b> Rename essentially acts as a &quot;smart&quot; search and replace, allowing the names
        of the following entities to be changed.  It correctly observes scoping and shadowing rules and renames
        module entities across files.
        <li><b>Applies To:</b> 
        <ol>
          <li> Local variables<sup>1,2</sup>
          <li> Subprograms<sup>3</sup>
          <li> Derived types
          <li> Module entities
          <li> Main programs
          <li> Namelists
          <li> Common blocks
          <li> Block data
        </ol>
        <small>1. Dummy subprogram arguments cannot be renamed</small><br>
        <small>2. Components of derived types cannot be renamed</small><br>
        <small>3. Subprograms cannot be renamed if they are declared External or Intrinsic</small>
      </ul>
    </div>
    
    <div class="homeitem3col">
      <a name="introimplicit"></a><h3>The Introduce Implicit None Refactoring</h3>
      <ul>
        <li><b>Purpose.</b> Introduce Implicit None adds an <tt>implicit none</tt> statement
        and adds explicit declarations for all variables that were previously declared implicitly.
        <li><b>Applies To:</b> 
        <ol>
          <li> Main programs
          <li> Subprograms
          <li> Modules
        </ol>
      </ul>
    </div>

  </div>
</div>    
EOHTML;

    # Generate the web page
    $App->generatePage($theme, $Menu, $Nav, $pageAuthor, $pageKeywords, $pageTitle, $html);
?>