diff --git a/DocxRenderer/convert_params.h b/DocxRenderer/convert_params.h index a0d5caef18..76a6a08fc7 100644 --- a/DocxRenderer/convert_params.h +++ b/DocxRenderer/convert_params.h @@ -1,4 +1,4 @@ -/* +/* * (c) Copyright Ascensio System SIA 2010-2023 * * This program is a free software product. You can redistribute it and/or @@ -33,13 +33,17 @@ namespace NSDocxRenderer { + /** + * @enum TextAssociationType + * @brief Specifies how extracted text is associated with layout elements. + */ enum class TextAssociationType { - tatBlockChar = 0, // Каждый символ во фрейме - tatBlockLine = 1, // Каждая линия - параграф во фрейме. Линии могут объединяться в рамках одного блока. - tatPlainLine = 2, // Каждая линия - параграф обычный - tatShapeLine = 3, // Каждая линия - параграф в шейпе. Линии могут объединяться в рамках одного блока. - tatPlainParagraph = 4, // Все линии объединяются в параграфы - tatParagraphToShape = 5 // Параграфы записываем в шейпы + tatBlockChar = 0, ///< Each character is placed in a frame. + tatBlockLine = 1, ///< Each line becomes a paragraph in a frame; lines may merge within one block. + tatPlainLine = 2, ///< Each line becomes a regular paragraph. + tatShapeLine = 3, ///< Each line becomes a paragraph in a shape; lines may merge within one block. + tatPlainParagraph = 4, ///< All lines are grouped into paragraphs. + tatParagraphToShape = 5 ///< Paragraphs are written into shapes. }; } diff --git a/X2tConverter/docs/Doxyfile b/X2tConverter/docs/Doxyfile new file mode 100644 index 0000000000..f3386baa99 --- /dev/null +++ b/X2tConverter/docs/Doxyfile @@ -0,0 +1,44 @@ +# Minimal Doxyfile for ONLYOFFICE Core - X2tConverter +# Generated to build HTML docs for C++ headers/sources in X2tConverter/src + +# Project +PROJECT_NAME = "ONLYOFFICE Core - X2tConverter" +PROJECT_BRIEF = "Doxygen documentation for X2tConverter C++ sources" +OUTPUT_DIRECTORY = . + +# Outputs +GENERATE_HTML = YES +HTML_OUTPUT = html +GENERATE_LATEX = NO + +# Input +INPUT = ../src \ + ../../Common/OfficeFileFormats.h \ + ../../UnicodeConverter/UnicodeConverter_Encodings.h \ + ../../DocxRenderer/convert_params.h +FILE_PATTERNS = *.h \ + *.hpp \ + *.cpp +RECURSIVE = YES + +# Parsing/formatting +EXTRACT_ALL = YES +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = YES +FULL_PATH_NAMES = NO +STRIP_FROM_PATH = ../.. +JAVADOC_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +MARKDOWN_SUPPORT = YES + +# UI +GENERATE_TREEVIEW = YES +SEARCHENGINE = YES + +# Diagrams (disable Graphviz dependency by default) +HAVE_DOT = NO + +# Warnings +QUIET = NO +WARN_IF_UNDOCUMENTED = NO +WARN_IF_DOC_ERROR = YES diff --git a/X2tConverter/docs/README.md b/X2tConverter/docs/README.md new file mode 100644 index 0000000000..93ba4b7961 --- /dev/null +++ b/X2tConverter/docs/README.md @@ -0,0 +1,35 @@ +# X2tConverter – Generate HTML API Documentation + +This guide explains how to install Doxygen and generate the HTML documentation for the C++ sources in `X2tConverter/src/`. + +## Prerequisites + +- Doxygen + +### Windows (PowerShell) +- Install Doxygen: + ```powershell + winget install doxygen + ``` + +### Linux (Debian/Ubuntu) +```bash +sudo apt-get update && sudo apt-get install -y doxygen +``` + +## Build the HTML docs + +From current directory, run: + +``` +doxygen ./Doxyfile +``` + +Output will be generated here: +- `html/index.html` + +Open that file in a browser to view the documentation. + +## Configuration notes + +- The Doxygen config lives at `Doxyfile`. diff --git a/X2tConverter/src/cextracttools.h b/X2tConverter/src/cextracttools.h index 4892e54f71..e61db236ed 100644 --- a/X2tConverter/src/cextracttools.h +++ b/X2tConverter/src/cextracttools.h @@ -255,20 +255,60 @@ namespace NExtractTools bool copyOrigin(const std::wstring& sFileFrom, const std::wstring& sFileTo); + /** + * @brief Mail merge related parameters. + * @details Parsed from the section in the input XML. + */ class InputParamsMailMerge { public: + /** + * @brief File name. + */ std::wstring* fileName; + /** + * @brief Sender's email address. + */ std::wstring* from; + /** + * @brief [Deprecated]. + */ std::wstring* jsonKey; + /** + * @brief Attachment format docx, pdf, html (see \ref AVS_OFFICESTUDIO_FILE_DOCUMENT). + */ int* mailFormat; + /** + * @brief Email body. + */ std::wstring* message; + /** + * @brief Number of records. + */ int* recordCount; + /** + * @brief Starting record index. + */ int* recordFrom; + /** + * @brief Ending record index. + */ int* recordTo; + /** + * @brief Email subject. + */ std::wstring* subject; + /** + * @brief Recipient's email address. + */ std::wstring* to; + /** + * @brief URL. + */ std::wstring* url; + /** + * @brief User ID. + */ std::wstring* userid; InputParamsMailMerge() { @@ -348,14 +388,25 @@ namespace NExtractTools } }; + /** + * @brief Thumbnail generation parameters. + * @details Parsed from the element in the input XML. + * Members map to child nodes: format, aspect, first, zip, width, height. + */ class InputParamsThumbnail { public: + /** @brief Output image format for thumbnails (bmp = 1, gif = 2, jpg = 3, png = 4). */ int* format; + /** @brief Fit mode: 0=stretch to width/height; 1=keep aspect; 2=use page metrics at 96 dpi (default). */ int* aspect; + /** @brief If true, generate a thumbnail for the first page only (default). If false, generate for all pages. */ bool* first; + /** @brief When generating thumbnails for all pages (first=false), output a ZIP archive with per-page images. */ bool* zip; + /** @brief Thumbnail width in pixels (default: 100). */ int* width; + /** @brief Thumbnail height in pixels (default: 100). */ int* height; InputParamsThumbnail() { @@ -410,9 +461,14 @@ namespace NExtractTools } }; + /** + * @brief Text-conversion related parameters. + * @details Parsed from the element in the input XML. + */ class InputParamsText { public: + /** @brief [Optional] Text association type (see \ref NSDocxRenderer::TextAssociationType). XML: . */ int* m_nTextAssociationType; InputParamsText() { @@ -448,11 +504,18 @@ namespace NExtractTools } }; + /** + * @brief Input constraints for particular input file types. + * @details Used for ZIP entries: compressed/uncompressed sizes and a name template. + */ class InputLimit { public: + /** @brief [Optional] Defines the total compressed file size for text documents/spreadsheets/presentations. */ ULONG64 compressed; + /** @brief [Optional] Defines the total uncompressed file size for text documents/spreadsheets/presentations. */ ULONG64 uncompressed; + /** @brief [Optional] Defines the name template for files which sizes are counted.(Example: "*.xml") */ std::wstring pattern; InputLimit() { @@ -490,38 +553,115 @@ namespace NExtractTools std::wstring m_sPdfOformMetaData; }; + /** + * @brief Container for all input parameters parsed from XML. + * @details Holds file paths, formats, CSV/TXT options, mail merge, thumbnail and + * text parameters, passwords, temporary paths, input limits, and flags + * controlling conversion behavior. + */ class InputParams { public: + /// \name File paths and metadata + /// @{ + /** @brief [Optional] Contains the document ID. For debugging purposes only. XML: . */ std::wstring* m_sKey; + /** @brief [Required] Source file path. XML: . */ std::wstring* m_sFileFrom; + /** @brief [Required] Destination file path. XML: . */ std::wstring* m_sFileTo; + /** @brief [Optional] Document title. Used for metadata in some output formats. XML: . */ std::wstring* m_sTitle; + /// @} + + /// \name Formats + /// @{ + /** @brief [Optional] Source format code. See \ref AVS_OFFICESTUDIO_FILE_DOCUMENT and related macros. Inferred from the file body or name when not specified. XML: . */ int* m_nFormatFrom; + /** @brief [Required] Destination format code. See \ref AVS_OFFICESTUDIO_FILE_DOCUMENT and related macros. XML: . */ int* m_nFormatTo; + /// @} + + /// \name CSV/TXT options + /// @{ + /** @brief [Optional] Character encoding (code page) for CSV/TXT (see \ref NSUnicodeConverter::Encodings "Encodings table"). XML: . */ int* m_nCsvTxtEncoding; + /** @brief [Optional] CSV delimiter type (see \ref TCsvDelimiter). XML: . */ int* m_nCsvDelimiter; + /** @brief [Optional] Custom delimiter character(s); overrides m_nCsvDelimiter. XML: . */ std::wstring* m_sCsvDelimiterChar; + /** @brief [Optional] Locale identifier (LCID) used in DOC and RTF to interpret strings when not specified in the file. XML: . */ int* m_nLcid; + /// @} + + /// \name Processing flags + /// @{ + /** @brief [Deprecated] Paid conversion flag. XML: . */ bool* m_bPaid; + /** @brief [Optional] Apply changes from the "changes" subfolder if present. XML: . */ bool* m_bFromChanges; + /** @brief [Optional] Suppress saving additional artifacts (such as the original file and changes.zip). XML: . */ bool* m_bDontSaveAdditional; + /// @} + + /// \name Fonts and themes + /// @{ + /** @brief [Deprecated] Path to AllFonts.js. XML: . */ std::wstring* m_sAllFontsPath; + /** @brief [Optional] Path to the directory containing font_selection.bin. XML: . */ std::wstring* m_sFontDir; + /** @brief [Optional] Built-in themes directory path. XML: . */ std::wstring* m_sThemeDir; + /// @} + + /// \name Nested parameter objects + /// @{ + /** @brief [Optional] Mail merge configuration. XML: . See \ref InputParamsMailMerge. */ InputParamsMailMerge* m_oMailMergeSend; + /** @brief [Optional] Thumbnail configuration. XML: . See \ref InputParamsThumbnail. */ InputParamsThumbnail* m_oThumbnail; + /** @brief [Optional] Text configuration. XML: . See \ref InputParamsText. */ InputParamsText* m_oTextParams; + /// @} + + /// \name Additional input options + /// @{ + /** @brief [Optional] JSON renderer options; supports keys like documentLayout, spreadsheetLayout, and watermark. See https://api.onlyoffice.com/docs/docs-api/additional-api/conversion-api/request/. XML: . */ std::wstring* m_sJsonParams; + /// @} + + /// \name Security and identifiers + /// @{ + /** @brief [Optional] Source file open password. XML: . */ std::wstring* m_sPassword; + /** @brief [Optional] Destination file save password. XML: . */ std::wstring* m_sSavePassword; + /** @brief [Optional] Document identifier. XML: . */ std::wstring* m_sDocumentID; + /// @} + + /// \name Temp and encoding + /// @{ + /** @brief [Optional] Explicit temp directory. XML: . */ std::wstring* m_sTempDir; + /** @brief [Optional] Treat Editor.bin as not Base64-encoded when true (default when absent). XML: . */ bool* m_bIsNoBase64; + /// @} + + /// \name Input constraints + /// @{ + /** @brief [Optional] Defines the OOXML file types for which the limits are specified (text documents/spreadsheets/presentations). This does not include other objects, like images. XML: ; values are \ref InputLimit. */ boost::unordered_map> m_mapInputLimits; + /// @} + + /// \name Output preferences + /// @{ + /** @brief [Optional] Request PDF/A output when applicable. XML: . */ bool* m_bIsPDFA; + /** @brief [Optional] List of extensions to also produce in the original format (Open in browser). XML: . */ std::wstring* m_sConvertToOrigin; - // output params + /// @} + mutable bool m_bOutputConvertCorrupted; mutable bool m_bMacro;