README

该项目是Dagstuhl出版社开发并用于Dagstuhl提交服务器上处理LaTeX提交的PHP类框架。其中大部分是关于从LaTeX文件中解析元数据。由于元数据信息以特定样式LaTeX宏（例如 \title{...}、\author{...}）或环境（例如 \begin{abstract}...\end{abstract}）的内容的形式出现，我们提供了...

一些通用的（低级）方法来解析LaTeX源代码中的宏/环境
LaTeX <-> UTF8的字符串转换支持

（这两个在更广泛的环境中可能很有用）以及

一个可定制的元数据读取器，它收集LaTeX文件中包含的元数据并将其转换为UTF8编码的字符串的有结构集合。

Dagstuhl出版社首先从LaTeX文件中删除所有注释，因此这些方法与无注释的LaTeX代码配合得最好。

安装：composer require dagstuhl/latex

1. 解析LaTeX文件的通用方法

要了解基本方法，让我们看一下LIPIcs示例文件。

$latexFile = new LatexFile('/resources/latex-examples/lipics-authors-v2021.1.3/lipics-v2021-sample-article.tex');

解析宏

上述文件包含宏 \documentclass[a4paper,UKenglish,cleveref, autoref, thm-restate]{lipics-v2021}，指定了底层样式文件和应用的选项。

以结构化方式读取此信息，只需执行以下操作

$documentClass = $latexFile->getMacro('documentclass');

$documentClass->getArgument();
// 'lipics-v2021'

$documentClass->getOptions();
// [ 'a4paper', 'UKenglish', 'cleveref', 'autoref', 'thm-restate' ]

如果宏可能多次出现，请使用 $latexFile->getMacros('...')，您将获得一个 LatexMacro 对象的数组

$sections = $latexFile->getMacros('section');
$sections[0]->getArgument();
// 'Typesetting instructions -- Summary'

如果宏有多个参数，请使用 $macro->getArguments() 方法将其参数作为字符串数组获取。以下是从LIPIcs文件中第一个作者宏的示例

\author{John Q. Public}{Dummy University Computing Laboratory, [optional: Address], Country \and My second affiliation, Country \and \url{http://www.myhomepage.edu} }{johnqpublic@dummyuni.org}{https://orcid.org/0000-0002-1825-0097}{(Optional) author-specific funding acknowledgements}

要将它拆分为不同的部分，只需做

$authors = $latexFile->getMacros('author');
$firstAuthor = $authors[0];
$firstAuthor->getArguments();
// [ 'John Q. Public', 'Dummy University ...', 'johnqpublic@dummyuni.org', ... ]

解析环境

要从LaTeX文件中将环境作为 LatexEnvironment 对象读取，请使用 $latexFile->getEnvironment('...'); 或 $latexFile->getEnvironments('...');。

例如，$latexFile->getEnvironment('abstract') 将读取摘要，而 $latexFile->getEnvironments('figure') 将返回所有图环境的数组。

可以使用 $environment->getContents() 方法捕获环境的全部内容（即 \begin{...} 和 \end{...} 之间的内容）。

要获取环境的全部LaTeX代码（包括 begin/end），请使用 $environment->getSnippet()。

注意：宏/环境的getter方法会在内部从LaTeX文件中移除类似 %... 的注释。因此，它们通过 ->getSnippet() 方法返回的LaTeX片段与注释不同

2. LaTeX到UTF8转换

从LaTeX文件转换元数据到UTF8可能非常复杂，这取决于底层LaTeX文件的结构和要转换的字符串的内容。在大多数情况下，MetadataString::toUtf8String() 应该可以完成这项工作。

$metaString = new MetadataString('Fran\c{c}ois M\"{u}ller-\"{A}hrenbaum recently proved that $a^2 + b^2 = c^2$'.);
$metaString->toUtf8String();
// 'François Müller-Ährenbaum recently proved that a² + b² = c².'

（作为第二个参数，MetadataString 构造函数接受一个LaTeX文件，该文件将用于解析未知宏。）

其他方向，即UTF8到LaTeX，由 Converter 类实现

Converter::convert('François Müller-Ährenbaum', Converter::MAP_UTF8_TO_LATEX);
// 'Fran\c{c}ois M\"{u}ller-\"{A}hrenbaum'

（请注意，无法从UTF8代码中重建数学环境，因此这基本上仅限于纯文本转换。）

3. 元数据读取器

为某个LaTeX documentclass 配置了样式描述php类（请参阅 src/Styles/StyleDescriptions）后，元数据提取和转换就非常简单了

$reader = $latexFile->getMetadataReader();
$metadata = $reader->getMetadata();
// array of metadata - structured and converted as specified in the StyleDescription file

4. 集成到Laravel项目中

当在Laravel项目中使用时，Storage类用于与文件交互（驱动器：本地）。要与您的LaTeX安装交互（例如，通过LatexCompiler类），您必须添加一个名为config/latex.php的配置文件，并提供以下值

return [
    'paths' => [
        'latex-bin' => env('LATEX_BIN'),        // path to your pdflatex binary
        'bibtex-bin' => env('BIBTEX_BIN'),      // path to your bibtex binary
        'pdf-info-bin' => env('PDF_INFO_BIN'),  // path to your pdf-info binary
        'resources' => env('LATEX_RESOURCES_FOLDER'), // resources folder (in case you want to use your own resources) 
    ],
    'styles' => [
        'registry' => \Your\Local\StylesRegistry::class // in case you want to use a custom styles registry
    ]
];

不在Laravel项目中，可以编写如下全局config函数

function config(): array
{
    return [ 
        'latex.paths.latex-bin' => 'path/to/pdflatex binary',
        'latex.paths.bibtex-bin' => 'path/to/bibtex binary',
        ...
    ];
}

dagstuhl / latex

维护者

详细信息