Added notes about eqrefs and non-breakable space before ref

[ischurov]

It is very surprising that one have to write (ref{eq:ref}) in order to make reference to an equation, so I believe it is better to discuss it in the docs at least.

Also, I found no way to express the correct syntax explicitly, because all these eqrefs (even in backticks and !bc do environment) are rendered by doconce. So I added spaces between parenthesis and eqref and asked the reader to remove it on their side. (Are there any better way to do it?)

[hplgit]

There is an automatic test that all references to equations do have surrounding parentheses! Consider

Equation ref{my:eq1} needs parentheses.

!bt
\begin{equation}
a = b
label{my:eq1}
\end{equation}
!et

Compilation results in

*** error: reference to equation label "my:eq1" is without parentheses
    the equation reference should be type set as (ref{my:eq1})

[ischurov]

Thanks. It seems that I used an outdated version of DocOnce without that test first and didn't checked on up-to-date one. However, I believe it is still worth to note it in the docs, isn't it? It is a natural question "how to make \eqref{…}" for anybody familiar with LaTeX and switching to DocOnce (like me).

Also I believe it worth to note that one do not need to prepend ref's with non-breakable space as it is common practice for LaTeX users.

[hplgit]

can agree that a note in the manual is in place (although I don't think any publisher will accept a reference to an equation without parentheses). A warning box is now included. As you indicated, it requires a trick to get the (ref{}) through the compilation process, so a doconce replace command is needed to fix this after the manual.html or manual.tex file is generated...

What do you mean by "prepend ref's with non-breakable space"?

[ischurov]

Thanks.

As for non-breakings spaces, it seems that it again was a problem with my outdated DocOnce. My first idea was to write something like See Figure~ref{fig:first} in DocOnce, just like I write See Figure~\ref{fig:first} in LaTeX (note a tilde before the ref), but in this case DocOnce just ignored my ref and left is as is (probably there were regex that expected a space before ref). It seems that now ~ref{...} processed correctly. However, maybe we still may consider adding a note to the docs that this nonbreakable space added automatically in LaTeX, so there's no need to add it manually before ref{...}.

[ischurov]

The suggestions were addressed in 5b59eda073a91b530b612547118846cc4f0ec745, so I'm closing this, thanks a lot!