diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf5e786e4..640c2e87e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,7 +45,7 @@ To run tests, run To run a specific test, run - npm run test fixture001 + npm run test build/fixture001 ## Testing and debugging the extension diff --git a/README.md b/README.md index 012acd374..df294b4df 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ [![Average time to resolve an issue](https://isitmaintained.com/badge/resolution/James-Yu/LaTeX-Workshop.svg)](https://github.com/James-Yu/LaTeX-Workshop/issues) [![Percentage of issues still open](https://isitmaintained.com/badge/open/James-Yu/LaTeX-Workshop.svg)](https://github.com/James-Yu/LaTeX-Workshop/issues) +[![TeX Live on Windows](https://github.com/James-Yu/LaTeX-Workshop/workflows/TeX%20Live%20on%20Windows/badge.svg)](https://github.com/James-Yu/LaTeX-Workshop/actions?query=workflow%3A%22TeX+Live+on+Windows%22) [![TeX Live on macOS](https://github.com/James-Yu/LaTeX-Workshop/workflows/TeX%20Live%20on%20macOS/badge.svg)](https://github.com/James-Yu/LaTeX-Workshop/actions?query=workflow%3A%22TeX+Live+on+macOS%22) [![TeX Live on Linux](https://github.com/James-Yu/LaTeX-Workshop/workflows/TeX%20Live%20on%20Linux/badge.svg)](https://github.com/James-Yu/LaTeX-Workshop/actions?query=workflow%3A%22TeX+Live+on+Linux%22) [![Docker on Linux](https://github.com/James-Yu/LaTeX-Workshop/workflows/Docker%20on%20Linux/badge.svg)](https://github.com/James-Yu/LaTeX-Workshop/actions?query=workflow%3A%22Docker+on+Linux%22) + LaTeX Workshop is an extension for [Visual Studio Code](https://code.visualstudio.com/), aiming to provide core features for LaTeX typesetting with Visual Studio Code. It also has a sibling extension, [LaTeX Utilities](https://marketplace.visualstudio.com/items?itemName=tecosaur.latex-utilities), providing extra features. This project won't be successful without contributions from the community, especially the current and past key contributors: diff --git a/src/components/manager.ts b/src/components/manager.ts index 1711a4835..f1147b490 100644 --- a/src/components/manager.ts +++ b/src/components/manager.ts @@ -56,9 +56,11 @@ export class Manager { this.initiatePdfWatcher() } - /* Returns the output directory developed according to the input tex path - and 'latex.outDir' config. If undefined is passed in, the default root - file is used. If there is not root file, './' is output. */ + /** + * Returns the output directory developed according to the input tex path + * and 'latex.outDir' config. If undefined is passed in, the default root + * file is used. If there is not root file, './' is output. + */ getOutDir(texPath?: string) { if (texPath === undefined) { texPath = this.rootFile @@ -300,9 +302,11 @@ export class Manager { return undefined } - /* This function returns a string array which holds all imported tex files - from the given `file`. If it is undefined, this function traces from the - root file, or return empty array if root is undefined */ + /** + * This function returns a string array which holds all imported tex files + * from the given `file`. If it is undefined, this function traces from the + * root file, or return empty array if root is undefined + */ getIncludedTeX(file?: string, includedTeX: string[] = []) { if (file === undefined) { file = this.rootFile @@ -350,13 +354,15 @@ export class Manager { return micromatch.some(file, globsToIgnore, { format } as any) } - /* This function is called when a root file is found or a watched file is - changed (in vscode or externally). It searches the subfiles, including - \input siblings, bib files, and related fls file to construct a file - dependency data structure in `this.cachedContent`. Noted that only the - provided `file` is re-parsed, together with any new files that were not - previously watched/considered. Since this function is called upon content - changes, this lazy loading should be fine. */ + /** + * This function is called when a root file is found or a watched file is + * changed (in vscode or externally). It searches the subfiles, including + * \input siblings, bib files, and related fls file to construct a file + * dependency data structure in `this.cachedContent`. Noted that only the + * provided `file` is re-parsed, together with any new files that were not + * previously watched/considered. Since this function is called upon content + * changes, this lazy loading should be fine. + */ parseFileAndSubs(file: string, onChange: boolean = false) { if (this.isExcluded(file)) { this.extension.logger.addLogMessage(`Ignoring ${file}`) @@ -380,8 +386,10 @@ export class Manager { } private cachedFullContent: string | undefined - /* This function returns the flattened content from the given file, - typically the root file. */ + /** + * This function returns the flattened content from the given file, + * typically the root file. + */ getContent(file?: string, fileTrace: string[] = []): string { // Here we make a copy, so that the tree structure of tex dependency // Can be maintained. For instance, main -> s1 and s2, both of which @@ -527,10 +535,12 @@ export class Manager { } } - /* This function parses the content of a fls attached to the given base tex - file. All input files are considered as included subfiles/non-tex files, - and all output files will be check if there are aux files related. If so, - the aux files are parsed for any possible bib file. */ + /** + * This function parses the content of a fls attached to the given base tex + * file. All input files are considered as included subfiles/non-tex files, + * and all output files will be check if there are aux files related. If so, + * the aux files are parsed for any possible bib file. + */ parseFlsFile(baseFile: string) { this.extension.logger.addLogMessage('Parse fls file.') const rootDir = path.dirname(baseFile) @@ -776,7 +786,9 @@ export class Manager { this.extension.completer.input.getGraphicsPath(file) } - // This function updates all completers upon tex-file changes, or active file content is changed. + /** + * This function updates all completers upon tex-file changes, or active file content is changed. + */ async updateCompleter(file: string, content: string) { this.extension.completer.citation.update(file, content) // Here we use this delay config. Otherwise, multiple updates may run diff --git a/src/utils/utils.ts b/src/utils/utils.ts index 9b2cfe69e..e7eaf08c7 100644 --- a/src/utils/utils.ts +++ b/src/utils/utils.ts @@ -47,7 +47,9 @@ export function getLongestBalancedString(s: string): string { return s.substring(0, i) } -// Given an input file determine its full path using the prefixes dirs +/** + * Given an input file determine its full path using the prefixes dirs + */ export function resolveFile(dirs: string[], inputFile: string, suffix: string = '.tex'): string | undefined { if (inputFile.startsWith('/')) { dirs.unshift('') @@ -83,18 +85,21 @@ export function convertFilenameEncoding(filePath: string): string | undefined { return undefined } -// prefix that server.ts uses to distiguish requests on pdf files from others. -// We use '.' because it is not converted by encodeURIComponent and other functions. -// See https://stackoverflow.com/questions/695438/safe-characters-for-friendly-url -// See https://tools.ietf.org/html/rfc3986#section-2.3 - +/** + * Prefix that server.ts uses to distiguish requests on pdf files from others. + * We use '.' because it is not converted by encodeURIComponent and other functions. + * See https://stackoverflow.com/questions/695438/safe-characters-for-friendly-url + * See https://tools.ietf.org/html/rfc3986#section-2.3 + */ export const pdfFilePrefix = 'pdf..' -// We encode the path with base64url after calling encodeURIComponent. -// The reason not using base64url directly is that we are not sure that -// encodeURIComponent, unescape, and btoa trick is valid on node.js. -// See https://en.wikipedia.org/wiki/Base64#URL_applications -// See https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/btoa#Unicode_strings +/** + * We encode the path with base64url after calling encodeURIComponent. + * The reason not using base64url directly is that we are not sure that + * encodeURIComponent, unescape, and btoa trick is valid on node.js. + * - https://en.wikipedia.org/wiki/Base64#URL_applications + * - https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/btoa#Unicode_strings + */ export function encodePath(url: string) { const s = encodeURIComponent(url) const b64 = Buffer.from(s).toString('base64') diff --git a/test/README.md b/test/README.md index 176f70cbe..b705b4931 100644 --- a/test/README.md +++ b/test/README.md @@ -1,5 +1,5 @@ ## Overview -### Tests of building TeX files +### Executing tests -We start a new VS Code instance each `fixture` directory in `fixtures/build`, and execute an appropriate test defined in `build.test.ts` while skipping other tests not related to the directory. Each test tries to build a TeX file in the directory. If a PDF file is not generated, the test fails. With this approach, we can debug the extension by opening a TeX file in the `fixture` directory if the test fails. +We start a new VS Code instance each `fixture` directory in `fixtures/build/` and `fixtures/viewer/`, and execute an appropriate test defined in `build.test.ts` while skipping other tests not related to the directory. Each test tries to build a TeX file in the directory. If a PDF file is not generated, the test fails. With this approach, we can debug the extension by opening a TeX file in the `fixture` directory if the test fails. diff --git a/viewer/README.md b/viewer/README.md index 18c0fe592..1ccfb86cd 100644 --- a/viewer/README.md +++ b/viewer/README.md @@ -2,7 +2,7 @@ The pdf viewer is based on [PDF.js](https://mozilla.github.io/pdf.js/) by Mozilla Foundation. Files are from the [prebuilt download version](https://mozilla.github.io/pdf.js/getting_started/#download). The reason we do not use `web/pdf_viewer.js` from `pdfjs-dist` package is that `pdf_viewer.js` does not provide features we need. `pdf_viewer.js` is much simpler than `viewer.js`. See [link](https://github.com/mozilla/pdf.js/issues/9318). -Mozilla [asks](https://mozilla.github.io/pdf.js/getting_started/) web developers to reskin `viewer.html` because Firefox users would think bugs of the viewer on the web site are ones of Firefox and would report them to the pdf.js team. See [link](https://github.com/mozilla/pdf.js/issues/5609). Our usage does not cause such a problem. +Mozilla [asks](https://mozilla.github.io/pdf.js/getting_started/) web developers to reskin `viewer.html` because Firefox users would think bugs of the viewer on the web site are ones of Firefox and would report them to the PDF.js team. See [link](https://github.com/mozilla/pdf.js/issues/5609). Our usage does not cause such a problem. We provide additional features by setting up new event listeners in `latexworkshop.js` for DOM objects in `viewer.html`. We do not and should not override functions defined by PDF.js. @@ -20,7 +20,7 @@ When opening a PDF file. In order. 4. pagesinit 5. documentloaded 7. documentinit -8. PDF da551cb... [...] (PDF.js: 2.2.228) (a log message is output) +8. `PDF da551cb... [...] (PDF.js: 2.2.228)` (a log message is output) 9. pagerendered 1. pagesloaded 1. textlayerrendered @@ -32,7 +32,7 @@ When reloading a PDF file. In order. 1. pagesinit 1. documentloaded 1. documentinit -1. PDF da551cb... [...] (PDF.js: 2.2.228) (a log message is output) +1. `PDF da551cb... [...] (PDF.js: 2.2.228)` (a log message is output) 1. pagerendered 1. pagesloaded 1. textlayerrendered