From dc76e7d50e8d66aca3c4f0a71070b87b2622a13f Mon Sep 17 00:00:00 2001 From: Alec Smecher Date: Tue, 14 Feb 2023 18:43:22 -0800 Subject: [PATCH] pkp/pkp-lib#7466 Review and sync upgrade documentation --- docs/IMPORTEXPORT | 188 --------------------------------------- docs/README-CSV.md | 49 ---------- docs/README-SITEMAP | 16 ---- docs/UPGRADE.md | 38 ++------ docs/dev/file-layout.txt | 22 ----- 5 files changed, 7 insertions(+), 306 deletions(-) delete mode 100644 docs/IMPORTEXPORT delete mode 100644 docs/README-CSV.md delete mode 100644 docs/README-SITEMAP delete mode 100644 docs/dev/file-layout.txt diff --git a/docs/IMPORTEXPORT b/docs/IMPORTEXPORT deleted file mode 100644 index 31d399923e3..00000000000 --- a/docs/IMPORTEXPORT +++ /dev/null @@ -1,188 +0,0 @@ -Import/Export Tools -=================== - -Import/export support is provided via plugins. These plugins can be accessed -over the web via the Journal Manager's "Import/Export Data" page, or via the -command line using the tools/importExport.php utility. - -OJS 2.0.1 ships with two of these plugins: the "Articles & Issues XML Plugin", -which allows import and export of articles and issues, and the "Users XML -Plugin", which allows import and export of users. - -Additional plugins may be installed simply by copying them into subdirectories -of the plugins/importexport directory; they will automatically be added to the -list of available plugins. - -Each import/export plugin has a unique name, defined in its PHP source code, by -which it can be invoked using the command line tool. To get a list of all -plugins via the command line, execute the following: - - php tools/importExport.php list - -To invoke a particular plugin from the command line, execute the following: - - php tools/importExport.php [pluginName] [arguments ...] - -For example, to get help from the NativeImportExportPlugin on its usage: - - php tools/importExport.php NativeImportExportPlugin usage - -Each plugin requires a different set of arguments; for information on each, -refer to its documentation. The two plugins that ship with OJS 2.0.1 are -described below. - -Developers of new plugins are encouraged to follow the standards set in the two -included plugins. For example: - - - Command-line argument styles should be consistent; - - Journals should be addressed by path; - - Local hrefs, such as , should be supported - only by the command line tool and should be discarded by the web- - based tool for security reasons; - - XML-based import/export plugins should use the XMLReader and XMLWriter - classes to ensure compatibility; - - etc. - - -Articles & Issues XML Plugin -============================ - -This plugin supports import and export of articles and issues in an XML format -based on the DTD supplied in plugins/importexport/native/native.dtd. It supports -the following root elements:
, , , and . - -The plugin is intended to provide an easy way to import back-issues into OJS, -often by converting data from another format (e.g. another dialect of XML or a -database). Only presentation-level data is supported, i.e. while it is possible -to import and export issue information, articles and article metadata, etc., it -is not possible to capture editorial data such as peer reviews, copyediting -comments, etc. - -There are two equivalent methods that can be used to access the plugin: -1. via the Journal Manager's "Import/Export Data" interface -2. via the tools/importExport.php command-line tool - -To get usage information for the command line tool, execute the following: - -php tools/importExport.php NativeImportExportPlugin usage - -The plugin can be used to move articles and issues from one OJS installation to -another, but note that this does NOT include the editorial history of the -documents. For example, if an article is peer-reviewed, the peer reviews will -not be part of the export document and will not be imported into the target -installation of OJS. - -Importing Data --------------- -Before importing data, ensure that the XML file validates against the DTD. -Many XML editors and tools such as xmllint are capable of validating XML files -against a DTD. - -The import XML will either link to (using the href tag) or encapsulate (using -the embed tag) files such as PDF articles and cover images. Using the embed tag -allows the file contents to be embedded directly in the XML document using -base64. Using the href tag allows the XML to refer to external files, either on -the server filesystem or at an external URL. Note that referring to local files -is disabled for security reasons when using the web-based import/export tool. - -Several root elements are supported for import documents:
, -, , and . The import process will differ depending on -which root element is chosen. For example, the import tool will need to know -which journal will receive the new issue when an import document begins with -. However, when using
or as the root node, the -import tool will need to know which journal, issue and section will receive the -new articles. The web-based import tool will prompt for this context as needed; -it will need to be specified manually when using the command-line tool. - -To import a document with the command-line tool, use the following syntax -(wrapped for clarity): - -php tools/importExport.php NativeImportExportPlugin import - [xmlFileName] [journal_path] [user_name] ... - -...where: - [xmlFileName] is replaced by the filename of the XML document to import - [journal_path] is the path of the journal to receive the import - document, as defined on the Site Administrator's "Hosted - Journals" interface. The path also appears in URLs to the - journal, i.e. in http://www.myjournal.com/index.php/demo/user, - "demo" is the journal path. - [user_name] is the username of the account that will receive control - of the imported documents. (Note that this does not mean that - authorship will be attributed to this account in the published - journal; however, the articles will appear in this user's - archive.) - -If
or root nodes are used, additional parameters will be -required to specify the section and issue. See the tool usage text for details. - -Exporting Data --------------- -Data can be exported either using the web interface or the command-line tool. -To export data using the command-line tool, use one of the following methods -(wrapped for clarity): - -php tools/importExport.php NativeImportExportPlugin export [xmlFileName] - [journal_path] articles [articleId1] [articleId2] ... - -php tools/importExport.php NativeImportExportPlugin export [xmlFileName] - [journal_path] article [articleId] - -php tools/importExport.php NativeImportExportPlugin export [xmlFileName] - [journal_path] issues [issueId1] [issueId2] ... - -php tools/importExport.php NativeImportExportPlugin export [xmlFileName] - [journal_path] issue [issueId] - -...where: - [xmlFileName] is replaced by the filename of the XML document to export - [journal_path] is the path of the journal from which to export data, - as defined on the Site Administrator's "Hosted Journals" - interface. The path also appears in URLs to the journal, i.e. - in http://www.myjournal.com/index.php/demo/user, "demo" is the - journal path. - -Each of these methods will export a document with a different root node: first -for multiple articles, then a single article, then multiple issues, then a -single issue. For each, one or multiple IDs need to be specified. - -Article IDs can be found in the editorial interface for many roles, e.g on a -submission's Summary, Review, or Editing pages. - -Issue IDs can be found in the Editor's "Future Issues" or "Back Issues" -interface. Select the issue you wish to export and examine the URL. It will -resemble the following: - http://www.myjournal.com/index.php/demo/editor/issueToc/12 - -In this example, the issue ID is 12. - -Example -------- -To export issue ID 3 from the journal having path "demo" to -the file "out.xml" (note that issue IDs can be database IDs or public IDs, with -public IDs taking precedence): - -php tools/importExport.php NativeImportExportPlugin export out.xml demo issue 3 - - -Users XML Plugin -================ - -This plugin supports import and export of users and their roles based on the -DTD supplied in plugins/importexport/users/users.dtd, with "users" as the root -element. - -To get usage information for the command line tool, execute the following: - -php tools/importExport.php UserImportExportPlugin usage - -For example, to export all users and their roles from the journal with path -"demo", execute the following: - -php tools/importExport.php UserImportExportPlugin export out.xml demo - -This plugin treats emails as unique user identifiers in order to ensure that -duplicate users are not created. If an existing user is found in the database -with the same email as an imported user, no additional user is created; the -roles described in the XML file are attributed instead to the existing user. -Usernames are treated likewise. diff --git a/docs/README-CSV.md b/docs/README-CSV.md deleted file mode 100644 index 7131ce81355..00000000000 --- a/docs/README-CSV.md +++ /dev/null @@ -1,49 +0,0 @@ -# Comma-Separated Values (CSV) Files - -## Importing into a Spreadsheet - -Some applications, including Microsoft Excel, do not correctly handle newlines -that are present within CSV data fields. - -For example, an address may include street information, followed by a newline, -followed by the city and province, followed by a newline, followed by a postal -code. The newlines are used to provide formatting for the field. This form of -data is valid and part of the CSV specification (please see [1] and [2]). - -Applications that do not correctly handle newlines treat data that follows a -newline as a new row of data. This leads to unexpected behaviour and errors -when importing CSV files. - -One workaround for this limitation is to use software that correctly processes -CSV files. - -For example, LibreOffice can be used to import a CSV file that contains newlines -in data fields. The resulting spreadsheet can either be used as is or LibreOffice -can be used to save the file in Microsoft Excel format (e.g. .xls). The file -can then be opened for editing in Microsoft Excel. - -In a similar way, Google Docs can be used to import the CSV file. Again, the -resulting spreadsheet may be used as is or Google Docs may be used to save the -file in Microsoft Excel format for editing in Microsoft Excel. - - -## LibreOffice - -LibreOffice may be obtained free of charge for Windows, Mac, and Linux: -https://www.libreoffice.org/ - -Alternately, Mac users can use NeoOffice, an OpenOffice port for the Mac: -http://www.neooffice.org - - -## Google Docs - -Google Docs require an Internet connection and a Google account: -http://docs.google.com - - -## Additional Information - -[1] http://tools.ietf.org/html/rfc4180 - -[2] http://en.wikipedia.org/wiki/Comma-separated_values diff --git a/docs/README-SITEMAP b/docs/README-SITEMAP deleted file mode 100644 index a3f5f3e341a..00000000000 --- a/docs/README-SITEMAP +++ /dev/null @@ -1,16 +0,0 @@ -Sitemap Documentation -Matt Crider, 12/1/2008 - -Adding a Sitemap to your website informs search engines about the URLs on your web site that you want to be indexed. This allows web crawlers to more intelligently index your site, and to index pages that may be difficult to find. Sitemaps also allow you to inform the engine other information about each page, such as modification frequency, when it was last changed, and how important it is in relation to your other pages. Please see http://www.sitemaps.org/protocol.php for more information. - -To enable a Sitemap for your site, you need to inform search engines about your sitemap URL. This is located at: - http://YOURDOMAIN.COM/PATH/TO/OxS/index.php/index/sitemap/ -You will have to change the domain your own site's domain, and also change the path to OJS/OCS to match the full path after the domain name. Leave the rest of the URL there--it is the path to a function that will dynamically generate the XML file for web crawlers to use. This file is referred to as a Sitemap index--A container to list all of the other Sitemaps (in this case, one for each journal). - -Please see http://www.sitemaps.org/protocol.php#informing for more information on informing search engines about your Sitemap. The quickest method is to submit the Sitemap directly to the search engines you wish to be listed under, but it is also a good idea to have a robots.txt file directing web crawlers to the Sitemap in case there are search engines you are not aware of crawling your site. - -Note that this will only inform web crawlers of the automatically generated sitemap, which will not include any of the additional tags that can be added to your sitemap (i.e. lastmod, changefreq, and priority). If you wish to customize your Sitemap, we suggest adding a new sitemap to the root directory of your OJS/OCS installation, and then copy the Sitemaps for each journal (produced when visiting http://YOURDOMAIN.COM/PATH/TO/OJS/index.php/YOURJOURNAL/sitemap/) into it. You can then add additional pages on your site and customize the XML with the additional available tags (http://www.sitemaps.org/protocol.php#xmlTagDefinitions). Further, you can put the Sitemap higher in the directory hierarchy, allowing you to add OJS/OCS and any other URLS that are below that directory level. - -Note also that if disable_path_info is set to 'On' in your config.inc.php file, you will have to use a different URL for submitting to search engines. The equivalent URL to index.php/index/sitemap with path info disabled is - index.php?journal=index&page=sitemap -This URL is not valid for your web browser, but search engines require ampersands (&) to be escaped and will be encoded correctly. \ No newline at end of file diff --git a/docs/UPGRADE.md b/docs/UPGRADE.md index 3a525a926ce..ef7a349f9a9 100644 --- a/docs/UPGRADE.md +++ b/docs/UPGRADE.md @@ -1,7 +1,7 @@ # Upgrading an OJS Installation Note: Before upgrading your installation, perform a complete backup of your -data files and database. If the upgrade process fails, you will need to recover +data files and database. If the upgrade process fails, you may need to recover from backup before continuing. If you are using PHP Safe Mode, please ensure that the max_execution_time @@ -10,32 +10,11 @@ or any other time limit (e.g. Apache's "Timeout" directive) is reached and the upgrade process is interrupted, manual intervention will be required. -## Upgrading from OJS 2.0.x, 2.1.x, 2.2.x, or 2.3.x +## Upgrading from OJS 2.x See [docs/UPGRADE-UNSUPPORTED](UPGRADE-UNSUPPORTED.md). -## Upgrading from OJS 2.4.x - -OJS 3.x is a major rewrite of Open Journal Systems, introducing numerous new -concepts and different approaches. The upgrade process from 2.x to 3.x does its -best to adapt old content to the new structures, but we strongly recommend -performing a test upgrade and exploring the new system before committing your -content to the upgrade. Downgrades from 3.x to 2.x will not be supported. - -Note that upgrading from OJS 2.4.x to OJS 3.0 will rearrange your submission -file storage, so be sure to back it up before running an upgrade. - -It is recommended that you execute the upgrade script under the same user -account that your server uses to execute OJS. If you cannot do this, you will -need to ensure file permissions in your files directory allow the upgrade -script to manage files there *before* the upgrade, and then reset file -permissions *after* the upgrade completes (so that OJS can manage files there -when invoked normally via the web). - -With that noted, follow the OJS 3.0 process described below. - - ## Upgrading from OJS 3.x Upgrading to the latest version of OJS involves two steps: @@ -43,8 +22,8 @@ Upgrading to the latest version of OJS involves two steps: - [Obtaining the latest OJS code](#obtaining-the-latest-ojs-code) - [Upgrading the OJS database](#upgrading-the-ojs-database) -It is highly recommended that you also review the release notes ([docs/RELEASE](RELEASE)) -and other documentation in the docs directory before performing an upgrade. +It is highly recommended that you also review the release notes ([RELEASE](RELEASE)) +and [How to Upgrade](https://docs.pkp.sfu.ca/dev/upgrade-guide/en/) before performing an upgrade. ### Obtaining the latest OJS code @@ -63,13 +42,10 @@ downloading the complete package for the latest release of OJS: OJS installation: - config.inc.php - - public/ - - Your uploaded files directory ("files_dir" in config.inc.php), if it - resides within your OJS directory + - public -- Synchronize new changes from config.TEMPLATE.inc.php to config.inc.php -- Replace the current OJS directory with the new OJS directory, moving the - old one to a safe location as a backup +- Move the old OJS installation directory to a safe location and move the new one into + its place - Be sure to review the Configuration Changes section of the release notes in docs/release-notes/README-(version) for all versions between your original version and the new version. You may need to manually add diff --git a/docs/dev/file-layout.txt b/docs/dev/file-layout.txt deleted file mode 100644 index a194a70bc6f..00000000000 --- a/docs/dev/file-layout.txt +++ /dev/null @@ -1,22 +0,0 @@ - ==================== - === OJS File Layout - ==================== - -The basic file layout is: - -classes/ - the bulk of the PHP class files (objects, DAOs, etc.) -config.inc.php - configuration file, in PHP ini style -dbscripts/ - SQL/XML scripts for creating/updating the database -docs/ - misc. documentation -help/ - help files (XML) -includes/ - any PHP functional include files (not class files) -index.php - front controller -js/ - JavaScript files -lib/ - third-party libraries (currently Smarty and ADOdb) -locale/ - i18n files (XML) -pages/ - controllers for handling a subset of related requests -styles/ - CSS files -templates/ - Smarty templates -tools/ - any misc. shell scripts or tools not part of the main code base - -The OJS2 code basically follows a rough MVC design -- at least as much as one can be forced onto PHP -- with "models" in the classes directory, "views" in the templates directory, and "controllers" in the pages directory.