File:  [mozdev] / maf / www / documentation.html
Revision 1.26: download - view: text, annotated - select for diffs - revision graph
Sat Oct 6 19:48:26 2018 UTC (15 months, 2 weeks ago) by pamadini
Branches: MAIN
CVS tags: HEAD
Align site with changeset ebc9c413b60c

<!-- MAIN CONTENT -->
<div class="maf-column-contents">

<div class="maf-box-warning">
  <p>The Mozilla Archive Format add-on is no longer maintained since
   <b>September 5, 2018</b>.</p>
</div>

<h2>Converting previously saved pages to other file formats</h2>
<p>The Saved Pages Conversion Wizard automates the process of opening the web
 pages you stored on your computer one by one and saving them again in a
 different file format. While the pages saved by this process usually look like
 the originals, in some cases the styling might not be replicated accurately.
 Because of this, the procedure never deletes the original files.</p>
<h3>Before you begin</h3>
<ul>
  <li><b>You should always keep a backup copy of the originals.</b></li>
  <li>If your pages were originally saved by the Mozilla Archive Format add-on,
   the conversion will generally be more accurate. If you used other programs or
   the standard Firefox save system, there is a higher chance that the converted
   pages will be different.</li>
  <li>Normally the originals will be moved to a separate folder after they have
   been converted, but this may not work for archives with very long file names.
   In this case, the conversion will be listed as failed, even though the files
   may have been converted successfully.</li>
</ul>
<p>The guided procedure can be started from the <b>File &raquo; Convert Saved
 Pages</b> menu item after installing the Mozilla Archive Format add-on. The
 procedure can also be started from the options window of the add-on.</p>
<img src="images/convertDialog-pageIntroduction.png" alt="">
<dl>
  <dt>Search for archived pages and ensure they can be opened in the future</dt>
  <dd>
  <p>This will search the folder where pages are currently saved, looking for
   MAFF and MHTML files that future versions of the browser will not be able to
   display. The default options will be used, and the next step of the procedure
   will be to select which files to convert.</p>
  </dd>
  <dt>Choose which file formats and folders to use</dt>
  <dd>
  <p>This allows you to follow the guided procedure in its entirety. The default
   options will still be preselected, but you will be able to change them as
   needed.</p>
  </dd>
</dl>
<h3>Destination file format</h3>
<img src="images/convertDialog-pageFormat.png" alt="">
<dl>
  <dt>HTML with support folder for data files</dt>
  <dd>
  <p>This file format is used by default in Firefox. Web pages are stored as
   file&nbsp;/&nbsp;folder pairs, for example <tt>Page.html</tt> and
   <tt>Page_files</tt>.</p>
  <p><b>This format provides the best compatibility</b> because it can be opened
   in any browser without installing additional software. It can also include
   large video and audio files efficiently.</p>
  <p>However, <b>the name of the folder cannot be changed</b> after the page is
   saved. The page may also become unreadable if the support folder is separated
   from the associated file, or if the file&nbsp;/&nbsp;folder pair is moved to
   a different file system where special characters, accented characters, or
   long file names may be lost. Backups may be significantly slower because the
   support folder often contains many small files.</p>
  </dd>
  <dt>MHTML archives</dt>
  <dd>
  <p>This file format was originally implemented by Microsoft Internet Explorer,
   and solves the issues with file&nbsp;/&nbsp;folder pairs because the entire
   web page is stored in a single file.</p>
  <p>However, MHTML files use more disk space and are not suitable for saving
   large video and audio files. MHTML files including such content would become
   very slow to load.</p>
  <p>This format provides generally good compatibility because it can be opened
   by Microsoft Internet Explorer and Google Chrome. On the other hand,
   <b>Firefox cannot open MHTML files</b> without installing an add-on. One
   compatible with future versions of Firefox does not currently exist, and
   additional external software would be required to open these files directly
   from the operating system's file manager.</p>
  </dd>
  <dt>MAFF archives</dt>
  <dd>
  <p>This file format was originally implemented by the Mozilla Archive Format
   add-on. MAFF files are standard ZIP files, and they can store multiple pages
   in a single archive.</p>
  <p>Since these archives are compressed, they are usually smaller than the
   equivalent MHTML archives or file&nbsp;/&nbsp;folder pairs, and can still
   include large video and audio files efficiently.</p>
  <p>However, browser support for this format is limited. While future versions
   of Firefox will still support the <tt>jar:</tt> protocol for reading the
   contents of MAFF files without installing an add-on, additional external
   software would be required to open these files directly from the operating
   system's file manager.</p>
  </dd>
</dl>
<h3>Source folder and file formats</h3>
<img src="images/convertDialog-pageSource.png" alt="">
<dl>
  <dt>Search this folder for source files</dt>
  <dd>
  <p>Depending on how many files are present in the source folder, building the
   list of files to convert may require some time. If you are working with large
   folder trees, you may want to repeat the procedure multiple times, converting
   one sub-folder at a time.</p>
  </dd>
  <dt>Search for source files in these formats</dt>
  <dd>
  <p>When looking for files to convert, MAFF and MHTML archives are recognized
   by their extension, respectively <tt>.maff</tt> and either <tt>.mht</tt> or
   <tt>.mhtml</tt>. Complete web pages are recognized because they have an
   associated support folder, for example <tt>Page.html</tt> and
   <tt>Page_files</tt>, but also <tt>Page</tt> (without extension) and
   <tt>Page_files</tt>. Web pages saved as single files, without support
   folders, are not included in the conversion.</p>
  <p>If you are using your browser in a language other than English, the
   recognition of additional support folder suffixes will be enabled. For
   example, if you are using your browser in French, a support folder named
   <tt>Page_fichiers</tt> is recognized, in addition to the English
   <tt>Page_files</tt>.</p>
  <p>If you previously saved pages using a browser in a different language than
   the current one, the support folder names may not be recognized correctly,
   and you might have to adjust the list of recognized suffixes in the <a
   href="#internalsettings">internal configuration settings</a>.</p>
  </dd>
  <dt>Download missing parts of the page when necessary</dt>
  <dd>
  <p>The conversion process will normally happen offline, because this mode is
   more reliable and faster. Pages saved by the Mozilla Archive Format add-on
   will always be converted correctly in this mode.</p>
  <p>If you used other programs or the standard Firefox save system, some images
   may not have been saved, but a reference to the original file may still be
   present. This option will make the browser work online, and may allow the
   recovery of some of the referenced images from the original website.</p>
  </dd>
</dl>
<h3>Destination folders</h3>
<img src="images/convertDialog-pageFoldersDest.png" alt="">
<p>You may want to place the converted files in a different folder from the
 originals if you are converting from a read-only source such as a CD-ROM or a
 DVD. The original folder structure is always preserved, so that if a source
 file is located in a sub-folder of the original folder, the converted file will
 be located in a sub-folder of the destination folder.</p>
<p>If the contents of the source folder cannot be modified, you can choose to
 leave the originals in place, instead of moving them to a separate archival
 folder after they have been converted successfully.</p>
<p>The converted files will be named according to the destination format. The
 extension in the source file name, if present, is always replaced with the
 correct extension for the file type. For MHTML, the <a
 href="#internalsettings">internal configuration settings</a> determine whether
 the <tt>.mht</tt> or <tt>.mhtml</tt> extension is used.</p>
<h3>Conversion</h3>
<img src="images/convertDialog-pageCandidates-select.png" alt="">
<p>You can exclude individual files from the conversion before the actual
 process begins. The list of files can be sorted by source file name or
 sub-folder. You can also enable additional columns to display the full
 paths.</p>
<p>If the destination file or support folder is already present, or if a file or
 support folder is already present in the archival folder where the source file
 would be moved after conversion, the source file name will appear in the list,
 but the selection checkbox will be disabled. This often indicates that the page
 was already converted successfully.</p>
<p>Click the <b>Convert</b> button to start the conversion. While the process is
 running, you can use the <b>Back</b> button or close the window to cancel.</p>
<img src="images/convertDialog-pageCandidates-results.png" alt="">
<p>When the operation is finished, you can see the count of how many files have
 been successfully converted and how many conversions failed. The icon near each
 file name indicates its current status: <img src="images/cbox-dis.gif" alt="">
 not selected, <img src="images/cbox-dis-check.gif" alt=""> already converted,
 <img src="images/cbox-status-enqueued.gif" alt=""> waiting for conversion, <img
 src="images/cbox-status-working.gif" alt=""> currently converting, <img
 src="images/cbox-status-failure.gif" alt=""> conversion failed, or <img
 src="images/cbox-status-success.gif" alt=""> conversion succeeded. You can
 click the <b>Finish</b> button to close the window, or use the <b>Back</b>
 button to retry the conversion with different settings.</p>
<p>Detailed information about the reasons for conversion failures is available
 in the Browser Console, accessible from the <b>Tools &raquo; Web Developer
 &raquo; Browser Console</b> menu item.</p>

<h2>Opening and saving web archives</h2>
<p>After installing the Mozilla Archive Format add-on, MAFF and MHTML archives
 can be displayed in the browser like any other saved page. On Windows, MAFF
 files can be opened easily from the operating system's file manager, but doing
 the same for MHTML requires creating new file associations from the options
 window of the add-on.</p>
<p><b>In Firefox, saving as MAFF or MHTML is disabled by default.</b></p>
<p>This functionality can be re-enabled from the options of the add-on, keeping
 in mind that future versions of the browser will not be able to open the pages
 saved in this way. The file types will then be available in the <i>Save As</i>
 dialog box, and the MAFF format will be used by default when saving complete
 web pages.</p>
<p>The following additional information will be stored when using either
 format:</p>
<ul>
  <li>The <b>original location</b> from which the page was saved.</li>
  <li>The <b>date and time</b> the page was saved.</li>
  <li>The <b>title</b> of the page, if present.</li>
  <li>The <b>character set</b> in effect at the time the page was saved. If this
   was changed manually using the <b>View &raquo; Text Encoding</b> menu item,
   the custom choice is remembered, allowing the document to be displayed
   correctly when it is reopened from the archive, even if it contains
   international characters.</p>
  </li>
</ul>
<p>This information is also preserved if you save an already archived page to a
 different file. If the original file is not a web archive, the following
 information is still preserved:</p>
<ul>
  <li>The <b>date and time</b> of the save operation is obtained from the last
   modification time.</li>
  <li>The <b>original location</b> may be available if the page was saved with
   Internet Explorer. If the page was saved using Firefox or SeaMonkey, the
   original location is not available, and the local file address will be stored
   in the archive instead.</p>
  </li>
</ul>
<p>You can save multiple tabs in an archive using the standard context menu on
 the tab strip or the context menu provided by the <a
 href="https://addons.mozilla.org/firefox/addon/4838">Multiple Tab Handler</a>
 add-on. For MHTML archives, multiple files are created, while for MAFF archives
 all the tabs are saved in a single file.</p>

<h2>Options</h2>
<img src="images/prefsDialog.png" alt="">
<dl>
  <dt>Open with Firefox</dt>
  <dd>
  <p>These options are displayed on Windows only, and allow opening MAFF and
   MHTML archives from the operating system's file manager. These file type
   associations are created only for the current user of the system, and are not
   removed when uninstalling.</p>
  </dd>
  <dt>Show the original location and save date of archived pages</dt>
  <dd>
  <p>This option allows disabling the information bar that is normally displayed
   when viewing an archived page.</p>
  </dd>
  <dt>Enable the "Save Page In Archive" functionality anyways</dt>
  <dd>
  <p>When the add-on is installed on Firefox, the ability to save pages as MAFF
   and MHTML is disabled by default. This option allows re-enabling this
   functionality, keeping in mind that future versions of the browser will not
   be able to open the pages saved in this way.</p>
  </dd>
</dl>

<h2><a name="internalsettings"></a>Internal configuration settings</h2>
<p>These settings are only available from the internal configuration page of the
 browser, and normally don't need to be changed.</p>
<dl>
  <dt><tt>extensions.maf.advanced.datafoldersuffixes</tt></dt>
  <dd>
  <p>Complete web pages are recognized by the Saved Pages Conversion Wizard
   because they have an associated support folder, with the same base name as
   the main file and a different suffix, for example <tt>Page.html</tt> and
   <tt>Page_files</tt>.</p>
  <p>This option contains a comma-separated list of the recognized suffixes. An
   additional suffix that depends on the current browser language may also be
   recognized without it being explicitly listed.</p>
  </dd>
  <dt><tt>extensions.maf.advanced.maff.compression</tt></dt>
  <dd>
  <p>Controls the compression level used when saving files in a MAFF archive.
   This can be <tt>best</tt> to use maximum compression for all files,
   <tt>dynamic</tt> to avoid re-compressing media files, and <tt>none</tt> to
   store all the files uncompressed.</p>
  </dd>
  <dt><tt>extensions.maf.advanced.maff.extendedmetadata</tt></dt>
  <dd>
  <p>With this preference enabled, history, text zoom, and scroll position are
   saved for each page. This additional information is ignored when the archive
   is opened.</p>
  </dd>
  <dt><tt>extensions.maf.advanced.maff.ignorecharacterset</tt></dt>
  <dd>
  <p>When this setting is enabled, the character set specified for pages saved
   inside MAFF archives is ignored. Enabling this option may be useful for
   troubleshooting problems with internationalization, but will cause saved
   pages to be displayed incorrectly in most cases.</p>
  </dd>
  <dt><tt>extensions.maf.advanced.maff.usejarprotocol</tt></dt>
  <dd>
  <p>If this preference is enabled, when you open a MAFF archive its contents
   will be accessed directly using the "jar:" protocol, without being
   extracted.</p>
  <p>However, if you enable this option, the archive files you open will be
   locked, and you will be unable to move, rename or delete them until the
   browser is closed.</p>
  </dd>
  <dt><tt>extensions.maf.advanced.mhtml.usemhtmlextension</tt></dt>
  <dd>
  <p>If this option is selected, and you do not type a file extension in the
   <i>Save As</i> dialog, or file extensions are hidden, the complete
   <tt>.mhtml</tt> extension will be appended to the file name of MHTML
   archives, instead of the more common <tt>.mht</tt> extension.</p>
  </dd>
  <dt><tt>extensions.maf.advanced.temp.clearonexit</tt></dt>
  <dd>
  <p>This option is enabled by default. If disabled, the contents of the
   temporary directory are preserved after the browser exits, and must be
   emptied manually.</p>
  </dd>
  <dt><tt>extensions.maf.advanced.temp.folder</tt></dt>
  <dd>
  <p>Use this preference to choose the location of the temporary files required
   to open and save the web archives. The contents of this folder will be lost
   if <tt>extensions.maf.advanced.temp.clearonexit</tt> is <tt>true</tt>.</p>
  <p>If not specified, this location defaults to a sub-folder of the system
   temporary folder, which is different for every browser profile.</p>
  </dd>
</dl>
</div>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>