<?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>Refactoring</h3>
      <p>Photran 4.0 is the first release to incorporate basic refactoring support.
      Currently, only two refactorings are supported, but more are in development.</p>

      <h4>On this page...</h4>
      <ol>
        <li><a href="#prep">Preparing to Use 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 Refactoring Support</h3>
      <h2>Setting Up the Indexer</h2>
      <p>In order to perform refactorings, Photran must keep track of what modules, subprograms, etc.
      are declared in every file in your project.  By default, it will do this by inspecting every
      file in your project as soon as you activate a refactoring, but this can take an annoyingly long
      time.  Instead, you can instruct Photran to update this information every time you save a file.
      To do this,</p>
      <ol>
        <li> Right-click on your project's folder in the Fortran Projects view
        <li> Click on Properties
        <li> Click on C/C++ Indexer (yes, C/C++ Indexer; we realize that's quirky)
        <li> Choose Photran Indexer from the drop-down list
        <li> Click OK
      </ol>
      <small>N.B. If you have a mixed C/C++ and Fortran project, you may not want to do this:
      Enabling the Photran Indexer will <i>disable</i> the CDT indexer, so features such as
      refactoring, Open Declaration, and content assist will no longer work in C/C++.</small>
      
      <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> Click on Fortran 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.
        <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 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);
?>