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 <[email protected]>
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
32wxString 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#ifndef __WIN32__
41 // just in case, add all known system directories to the search stack
42 SystemDirsAppend( &basePaths );
43#endif
44
45#if defined( DEBUG )
46 basePaths.Show( wxString( __func__ ) + wxS( ": basePaths" ) );
47#endif
48
49 // By default, the documentation from kicad-doc is installed to a folder called "help" with
50 // subdirectories for all supported languages. Although this can be changed at build-time by
51 // overwriting ${KICAD_DOC_PATH}, the best guess KiCad can make is that help files are always
52 // located in a folder named "help". If no translation matching the current locale settings is
53 // available, the English version will be returned instead.
54
55 wxLocale* currentLocale = Pgm().GetLocale();
56 wxArrayString localeNameDirs;
57
58 // canonical form of the current locale (e.g., "fr_FR")
59 localeNameDirs.Add( currentLocale->GetCanonicalName() );
60
61 // short form of the current locale (e.g., "fr")
62 // wxLocale::GetName() does not always return the short form
63 localeNameDirs.Add( currentLocale->GetName().BeforeLast( wxS( '_' ) ) );
64
65 // plain English (in case a localised version of the help file cannot be found)
66 localeNameDirs.Add( wxS( "en" ) );
67
68 for( wxString& locale : localeNameDirs )
69 {
70 SEARCH_STACK docPaths;
71
72 for( wxString& base : basePaths )
73 {
74 wxFileName path( base, wxEmptyString );
75
76 // add <base>/help/<locale>/
77 path.AppendDir( wxS( "help" ) );
78 path.AppendDir( locale );
79 docPaths.AddPaths( path.GetPath() );
80
81 // add <base>/doc/help/<locale>/
82 path.InsertDir( path.GetDirCount() - 2, wxS( "doc" ) );
83 docPaths.AddPaths( path.GetPath() );
84
85 // add <base>/doc/kicad/help/<locale>/
86 path.InsertDir( path.GetDirCount() - 2, wxS( "kicad" ) );
87 docPaths.AddPaths( path.GetPath() );
88 }
89
90#if defined( DEBUG )
91 docPaths.Show( wxString( __func__ ) + wxS( ": docPaths (" ) + locale + wxS( ")" ) );
92#endif
93
94 // search HTML first, as it is the preferred format for help files
95 wxLogTrace( tracePathsAndFiles, wxS( "Checking SEARCH_STACK for file %s.html" ),
96 aBaseName );
97 helpFile = docPaths.FindValidPath( aBaseName + wxS( ".html" ) );
98
99 if( !helpFile.IsEmpty() )
100 {
101 // prepend URI protocol to open the file in a browser
102 helpFile = wxS( "file://" ) + helpFile;
103 break;
104 }
105
106 // search PDF only when no corresponding HTML file was found
107 wxLogTrace( tracePathsAndFiles, wxS( "Checking SEARCH_STACK for file %s.pdf" ), aBaseName );
108 helpFile = docPaths.FindValidPath( aBaseName + wxS( ".pdf" ) );
109
110 if( !helpFile.IsEmpty() )
111 break;
112 }
113
114 return helpFile;
115}
static wxString GetDocumentationPath()
Gets the documentation path, which is the base path for help files.
Definition: paths.cpp:333
Look for files in a number of paths.
Definition: search_stack.h:42
void AddPaths(const wxString &aPaths, int aIndex=-1)
Insert or append path(s).
The common library.
const wxChar *const tracePathsAndFiles
Flag to enable path and file name debug output.
see class PGM_BASE
wxString SearchHelpFileFullPath(const wxString &aBaseName)
Return the help file's full path.
KIWAY Kiway & Pgm(), KFCTL_STANDALONE
The global Program "get" accessor.
Definition: single_top.cpp:111
void SystemDirsAppend(SEARCH_STACK *aSearchStack)
Append system places to aSearchStack in a platform specific way and pertinent to KiCad programs.
System directories search utilities.
wxLogTrace helper definitions.