Skip to content

Troubleshooting

How do I use this module?

DOC to HTML has no page of its own where you upload documents. It is a widget on a text field.

  1. Install LibreOffice and the module, see Installation.
  2. Set the widget DOC to HTML on the field in Manage form display.
  3. Edit a node, open the section DOC to HTML file under the field, upload the document and click Convert.

The full tutorial is in Getting started. To try a document without a content type, use the Test Wizard, see Configuration.

I do not see the DOC to HTML section

  • The widget must be set on the field in Manage form display.
  • The field must be of type text_long or text_with_summary.
  • Your role needs the permission use doc to html widget, see Permissions.

LibreOffice is not found

The status report or drush dth:version says that LibreOffice is missing.

  • Check that LibreOffice is installed on the machine where PHP runs, not only on your computer. In Docker and DDEV, it must be in the web or PHP container.
  • Check Base path for LibreOffice and Command on the LibreOffice Settings page. The command is the name only, such as soffice.
  • Run the binary as the web server user: sudo -u www-data /usr/bin/soffice --version.

The conversion times out

  • Raise Conversion timeout on the LibreOffice Settings page.
  • Check that the document opens in LibreOffice. A damaged file can make the process hang.
  • The first run on a fresh system can be slow, because LibreOffice creates its profile. Each conversion creates a new profile, so large documents and small servers need a higher timeout.

proc_open is not available

The status report shows a requirement for proc_open. The module needs it to start LibreOffice and to stop it on timeout. There is no fallback to shell_exec() in 2.1.x.

Remove proc_open from disable_functions in the php.ini used by the web server and by Drush, then restart PHP.

The conversion fails with a generic message

The editor sees a short message. The details are in the Drupal log, channel doc_to_html, at Reports > Recent log messages. The log has the output of LibreOffice, shortened.

The text is empty, or the editor shows raw HTML

  • Check the text format set in the widget settings. The format must allow the tags in the converted HTML.
  • Headings, tables or underlines disappear after Convert: the field uses a restricted format. Core's Basic HTML allows h2 to h6 but not h1, table or u, and the editor removes them. Set Text format for converted content to Full HTML or to a format that allows them.
  • If the user cannot use the chosen format, the current format stays and a message tells the user. Give the user access to the format or choose another one.
  • Check Regular expression to extract body content and the match index. With a regex without a capture group, use index 0.

Images are broken

  • Check that the text format allows the img tag.
  • Check the Image upload directory of the widget and that the web server can write there.
  • Images of other types than png, jpg, jpeg, gif and webp are removed. See Images.

The original document is not on the node

  • Check that Source file field is set in the widget settings and that the field is a File or Image field on the same bundle.
  • Save the node. Convert alone does not save anything.
  • Check that the field does not require input the widget cannot give, such as a required description.

A document is not converted, or the upload is refused

Check that the file type is enabled in Basic Settings. Only DOC and DOCX are on by default. ODT, RTF and PPTX are off and you must enable them there. From 2.1.0 they convert for real.

Since 2.1.0

In 2.0.x the ODT, RTF and PPTX switches exist, but those documents do not convert. See Versions.

The title appears twice

The document starts with its title, and the node has a title field. Enable Remove the first heading of the document in the widget settings. A conversion then removes the heading and fills the empty title with its text. See The widget. A DOM regex can do the removal too, see Suggested DOM regex rules.

Two columns are kept as a style

A document with two columns comes out as a block with a column-count style. The result depends on the text format. A format that removes the style attribute drops the columns. Choose a format that allows it, or accept one column. The formatter library adds a gap between the columns, see Theming.

The images lose their alternative text

A .docx loses the alternative text of the images, and an .odt keeps it. This comes from the LibreOffice HTML export, not from the module. Use the .odt format if you need the alternative text, or write it again in the editor.

The images keep old attributes

LibreOffice leaves attributes such as align, border and name on the img tags. The module keeps them. Remove them with the rule in Suggested DOM regex rules.

Drush cannot find the file

drush dth:convert accepts an absolute path, a path relative to the Drupal root, or a path relative to the directory your shell was in. It tries them in that order. If none exists, it prints "File not found".

Since 2.1.0

In 2.0.x only a path that works from the Drupal root is found. See Versions.

The HTML is full of styles and empty paragraphs

LibreOffice writes inline styles, western classes, font tags and empty paragraphs. The Suggested DOM regex rules remove them. Try a rule in the Test Wizard first.