Re: ox-publish: Some starting problems

[Nick Dokos]

[Answers to some of the questions inline]

c.buhtz@posteo.jp writes:

> 1.  Is this mailing list the right place to discuss ox-publish
> related topics? The ox-publish.el only contains two e-mail
> addresses?
>
Yes.

> 2.  Because ox-publish is skipping "unmodified files" I deleted all
> HTML files between the publish-runs just to be sure that there are
> no side effects. But now when my output directory is totally empty
> ox-publish still keeps saying that it is skipping the unmodified
> files. So nothing is generated anymore. How can I handle that? Maybe
> resetting the "unmodified" flag somewhere? Or shouldn't ox-publish
> not only check for modifications but if there is something earlier
> generated content exist?
>
Org mode records the time when a file was published and compares it to
the last modification time to decide whether to publish or not. It
does not have a dependency mechanism like `make' to figure things
out. As you found out, you can force it by calling it with a `t'
argument for the `force' parameter. You can do this interactively with
`C-u M-x org-publish'. See the "Triggering Publication" section of the
manual:

  (info "(org)Triggering Publication")

That section also points you to the variable
`org-publish-use-timestamps-flag': if you set that to `nil', no
timestamp checking is done.

The timestamps are kept in the directory named by the variable
`org-publish-timestamp-directory' whose default value is
"~/.org-timestamps/".

> 4.  ox-publish ignores newlines. Two short lines in the org-file
> becomes one line in the HTML content.
>

That is how HTML export (and publishing) works: the browser does its
own layout of HTML content and you have no say in that (except for
`verbatim' things that are pre-formatted).

> 5.  I am not totally new to Emacs but quit fresh. So I have two
> questions about how to handle the documentation and help
> informations here.  a) I tried to "descrbie" the mode
> "ox-publish". But Emacs only offers me an "describe-mode" which
> describe all currently existing nodes. There is nothing like
> "describe-mode MODENAME". How can I handle that?

There is no such mode: `ox-publish' is (part of) the name of the file
that contains the code that is used for publishing - in particular
it contains the code of the function `org-publish'. You can get
the doc string of the function with `C-h f org-publish'.

> b) I another thread I was pointed to
> https://orgmode.org/manual/Publishing-options.html . There is no
> description about the options they are only listed. This does not
> help me. Maybe there are some useful options that could solve some
> of my problems. But without description I am not able to decide or
> know.
>

Read the first paragraph of that section carefully:

,----
| The property list can be used to set many export options for the HTML
| and LaTeX exporters.  In most cases, these properties correspond to
| user variables in Org.  The table below lists these properties along
| with the variable they belong to.  See the documentation string for
| the respective variable for details.
`----

So to find out e.g. what the option ‘:archived-trees’ does, you have
to ask for the doc string of the variable ‘org-export-with-archived-trees’.
You can do that with `C-h v org-export-with-archived-trees' or more easily
by putting the cursor on the name and typing `C-h v RET`.

-- 
Nick

"There are only two hard problems in computer science: cache
invalidation, naming things, and off-by-one errors." -Martin Fowler