KiCad PCB EDA Suite
searchhelpfilefullpath.cpp
Go to the documentation of this file.
1 /*
2  * This program source code file is part of KiCad, a free EDA CAD application.
3  *
4  * Copyright (C) 2014-2015 CERN
5  * Copyright (C) 2014-2021 KiCad Developers, see AUTHORS.txt for contributors.
6  * @author Maciej Suminski <maciej.suminski@cern.ch>
7  *
8  * This program is free software: you can redistribute it and/or modify it
9  * under the terms of the GNU General Public License as published by the
10  * Free Software Foundation, either version 2 of the License, or (at your
11  * option) any later version.
12  *
13  * This program is distributed in the hope that it will be useful, but
14  * WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16  * General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License along
19  * with this program. If not, see <http://www.gnu.org/licenses/>.
20  */
21 
22 #include <common.h>
23 #include <pgm_base.h>
24 #include <paths.h>
25 #include <systemdirsappend.h>
26 #include <trace_helpers.h>
27 
28 #include <wx/arrstr.h>
29 #include <wx/log.h>
30 
31 
32 wxString SearchHelpFileFullPath( const wxString& aBaseName )
33 {
34  SEARCH_STACK basePaths;
35  wxString helpFile;
36 
37  // help files are most likely located in the documentation install path
38  basePaths.Add( PATHS::GetDocumentationPath() );
39 
40  // just in case, add all known system directories to the search stack
41  SystemDirsAppend( &basePaths );
42 
43 #if defined( DEBUG )
44  basePaths.Show( wxString( __func__ ) + ": basePaths" );
45 #endif
46 
47  // By default, the documentation from kicad-doc is installed to a folder called "help" with
48  // subdirectories for all supported languages. Although this can be changed at build-time by
49  // overwriting ${KICAD_DOC_PATH}, the best guess KiCad can make is that help files are always
50  // located in a folder named "help". If no translation matching the current locale settings is
51  // available, the English version will be returned instead.
52 
53  wxLocale* currentLocale = Pgm().GetLocale();
54  wxArrayString localeNameDirs;
55 
56  // canonical form of the current locale (e.g., "fr_FR")
57  localeNameDirs.Add( currentLocale->GetCanonicalName() );
58 
59  // short form of the current locale (e.g., "fr")
60  // wxLocale::GetName() does not always return the short form
61  localeNameDirs.Add( currentLocale->GetName().BeforeLast( '_' ) );
62 
63  // plain English (in case a localised version of the help file cannot be found)
64  localeNameDirs.Add( "en" );
65 
66  for( wxString& locale : localeNameDirs )
67  {
68  SEARCH_STACK docPaths;
69 
70  for( wxString& base : basePaths )
71  {
72  wxFileName path( base, wxEmptyString );
73 
74  // add <base>/help/<locale>/
75  path.AppendDir( "help" );
76  path.AppendDir( locale );
77  docPaths.AddPaths( path.GetPath() );
78 
79  // add <base>/doc/help/<locale>/
80  path.InsertDir( path.GetDirCount() - 2, "doc" );
81  docPaths.AddPaths( path.GetPath() );
82 
83  // add <base>/doc/kicad/help/<locale>/
84  path.InsertDir( path.GetDirCount() - 2, "kicad" );
85  docPaths.AddPaths( path.GetPath() );
86  }
87 
88 #if defined( DEBUG )
89  docPaths.Show( wxString( __func__ ) + ": docPaths (" + locale + ")" );
90 #endif
91 
92  // search HTML first, as it is the preferred format for help files
93  wxLogTrace( tracePathsAndFiles, "Checking SEARCH_STACK for file %s.html", aBaseName );
94  helpFile = docPaths.FindValidPath( aBaseName + ".html" );
95 
96  if( !helpFile.IsEmpty() )
97  {
98  // prepend URI protocol to open the file in a browser
99  helpFile = "file://" + helpFile;
100  break;
101  }
102 
103  // search PDF only when no corresponding HTML file was found
104  wxLogTrace( tracePathsAndFiles, "Checking SEARCH_STACK for file %s.pdf", aBaseName );
105  helpFile = docPaths.FindValidPath( aBaseName + ".pdf" );
106 
107  if( !helpFile.IsEmpty() )
108  break;
109  }
110 
111  return helpFile;
112 }
wxString FindValidPath(const wxString &aFileName) const
Definition: search_stack.h:70
const wxChar *const tracePathsAndFiles
Flag to enable path and file name debug output.
System directories search utilities.
Look for files in a number of paths.
Definition: search_stack.h:41
KIWAY Kiway & Pgm(), KFCTL_STANDALONE
The global Program "get" accessor.
Definition: single_top.cpp:106
static wxString GetDocumentationPath()
Gets the documentation path, which is the base path for help files.
Definition: paths.cpp:275
wxString SearchHelpFileFullPath(const wxString &aBaseName)
Return the help file's full path.
void SystemDirsAppend(SEARCH_STACK *aSearchStack)
Append system places to aSearchStack in a platform specific way and pertinent to KiCad programs.
wxLogTrace helper definitions.
see class PGM_BASE
The common library.
void AddPaths(const wxString &aPaths, int aIndex=-1)
Insert or append path(s).