\documentclass[DIV=13,%
               BCOR=0mm,%
               headinclude=false,%
               footinclude=false,open=any,%
               fontsize=10pt,%
               oneside,%
               paper=a5]%
               {scrbook}



\usepackage[noautomatic]{imakeidx}



\usepackage{microtype}
\usepackage{graphicx}
\usepackage{alltt}
\usepackage{verbatim}
\usepackage[shortlabels]{enumitem}
\usepackage{tabularx}
\usepackage[normalem]{ulem}
\def\hsout{\bgroup \ULdepth=-.55ex \ULset}
% https://tex.stackexchange.com/questions/22410/strikethrough-in-section-title
% Unclear if \protect \hsout is needed. Doesn't looks so
\DeclareRobustCommand{\sout}[1]{\texorpdfstring{\hsout{#1}}{#1}}
\usepackage{wrapfig}

% avoid breakage on multiple <br><br> and avoid the next [] to be eaten
\newcommand*{\forcelinebreak}{\strut\\*{}}

\newcommand*{\hairline}{%
  \bigskip%
  \noindent \hrulefill%
  \bigskip%
}

% reverse indentation for biblio and play

\newenvironment*{amusebiblio}{
  \leftskip=\parindent
  \parindent=-\parindent
  \smallskip
  \indent
}{\smallskip}

\newenvironment*{amuseplay}{
  \leftskip=\parindent
  \parindent=-\parindent
  \smallskip
  \indent
}{\smallskip}

\newcommand*{\Slash}{\slash\hspace{0pt}}


% http://tex.stackexchange.com/questions/3033/forcing-linebreaks-in-url
\PassOptionsToPackage{hyphens}{url}\usepackage[hyperfootnotes=false,hidelinks,breaklinks=true]{hyperref}
\usepackage{bookmark}

\usepackage{fontspec}
\usepackage{polyglossia}
\setmainlanguage{english}
\setmainfont{texgyrepagella-regular.otf}[Script=Latin,%
 Ligatures=TeX,%
 Path=/usr/share/texmf/fonts/opentype/public/tex-gyre/,%
 BoldFont=texgyrepagella-bold.otf,%
 BoldItalicFont=texgyrepagella-bolditalic.otf,%
 ItalicFont=texgyrepagella-italic.otf]
\setmonofont{cmuntt.ttf}[Script=Latin,%
 Ligatures=TeX,%
 Scale=MatchLowercase,%
 Path=/usr/share/fonts/truetype/cmu/,%
 BoldFont=cmuntb.ttf,%
 BoldItalicFont=cmuntx.ttf,%
 ItalicFont=cmunit.ttf]
\setsansfont{cmunss.ttf}[Script=Latin,%
 Ligatures=TeX,%
 Scale=MatchLowercase,%
 Path=/usr/share/fonts/truetype/cmu/,%
 BoldFont=cmunsx.ttf,%
 BoldItalicFont=cmunso.ttf,%
 ItalicFont=cmunsi.ttf]
\newfontfamily\englishfont{texgyrepagella-regular.otf}[Script=Latin,%
 Ligatures=TeX,%
 Path=/usr/share/texmf/fonts/opentype/public/tex-gyre/,%
 BoldFont=texgyrepagella-bold.otf,%
 BoldItalicFont=texgyrepagella-bolditalic.otf,%
 ItalicFont=texgyrepagella-italic.otf]



\renewcommand*{\partpagestyle}{empty}


% global style

\pagestyle{plain}




\usepackage{indentfirst}

% remove the numbering
\setcounter{secnumdepth}{-2}

% remove labels from the captions
\renewcommand*{\captionformat}{}
\renewcommand*{\figureformat}{}
\renewcommand*{\tableformat}{}
\KOMAoption{captions}{belowfigure,nooneline}
\addtokomafont{caption}{\centering}







\deffootnote[3em]{0em}{4em}{\textsuperscript{\thefootnotemark}~}


\addtokomafont{disposition}{\rmfamily}
\addtokomafont{descriptionlabel}{\rmfamily}


\frenchspacing
% avoid vertical glue
\raggedbottom

% this will generate overfull boxes, so we need to set a tolerance
% \pretolerance=1000
% pretolerance is what is accepted for a paragraph without
% hyphenation, so it makes sense to be strict here and let the user
% accept tweak the tolerance instead.
\tolerance=200
% Additional tolerance for bad paragraphs only
\setlength{\emergencystretch}{30pt}

% (try to) forbid widows/orphans
\clubpenalty=10000
\widowpenalty=10000





% given that we said footinclude=false, this should be safe
\setlength{\footskip}{2\baselineskip}

\title{Integration with external sites}
\date{}
\author{}
\subtitle{}




% https://groups.google.com/d/topic/comp.text.tex/6fYmcVMbSbQ/discussion
\hypersetup{%
pdfencoding=auto,
pdftitle={Integration with external sites},%
pdfauthor={},%
pdfsubject={},%
pdfkeywords={doc}%
}


\begin{document}






  \begin{titlepage}


  \strut\vskip 2em
  \begin{center}

  {\usekomafont{title}{\huge Integration with external sites\par}}%
  \vskip 1em
  
  \vskip 2em
  
  \vskip 1.5em



   
   \vfill



  
    \strut\par
  


  \end{center}


     \end{titlepage}
     
     \cleardoublepage



\tableofcontents
% start a new right-handed page

\cleardoublepage



\section{Embedding an existing text}


Say the URL of the text you want to embed is
\href{https://amusewiki.org/library/bookbuilder-tutorial}{\texttt{https://amusewiki.org/library/bookbuilder-tutorial}}, you can add an
iframe with
\href{https://amusewiki.org/library/bookbuilder-tutorial/embed}{\texttt{https://amusewiki.org/library/bookbuilder-tutorial/embed}} to have
the infobox with the downloads.


Example:


\begin{alltt}
<iframe src="https://amusewiki.org/library/bookbuilder-tutorial/embed"
        width="700px"
        height="200px">
</iframe>
\end{alltt}

\section{Non-interactive creation of texts}


This procedure lacks any human interaction and it relies completely on
the HTML conversion to be good enough. Worst case scenario, you are
going to get a text which needs fixing.


You need an existing user on the site.


The API endpoint is \texttt{/remote/create}, e.g.
\texttt{https://staging.amusewiki.org/remote/create}.


You need to do a \texttt{POST} request with some mandatory and some optional parameters


Request:


\begin{alltt}
\$ curl -F \_\_auth\_user=\$username \textbackslash{}
       -F \_\_auth\_pass=\$password \textbackslash{}
       -F title=Test \textbackslash{}
       -F textbody='Hello <em>hello</em>' \textbackslash{}
       https://staging.amusewiki.org/remote/create
\end{alltt}


Response is a JSON string, which holds the URL of the text which is
going to be created and the job URL with the publishing.


\begin{alltt}
\{
  "url":"https://staging.amusewiki.org/library/test",
  "job":"https://staging.amusewiki.org/tasks/status/17097"
\}
\end{alltt}


If you are missing some mandatory parameters you get an error:


\begin{alltt}
curl -F \_\_auth\_user=\$username \textbackslash{}
     -F \_\_auth\_pass=\$password \textbackslash{}
     -F textbody='Hello <em>hello</em>' \textbackslash{}
     https://staging.amusewiki.org/remote/create
\end{alltt}


Response:


\begin{alltt}
\{"error":"Missing mandatory title and textbody parameters"\}
\end{alltt}


If you miss the the authentication parameters, you get a 401 response.


To create a new special page, append\footnote{Actually, \texttt{/remote/create} is an alias for \texttt{/remote/create/library}} \texttt{special} to the endpoint:


\begin{alltt}
curl -F \_\_auth\_user=\$username \textbackslash{}
     -F \_\_auth\_pass=\$pwd \textbackslash{}
     -F title='My special' \textbackslash{}
     -F textbody='Hello <em>special</em>' \textbackslash{}
     https://staging.amusewiki.org/remote/create/special
\end{alltt}


Response:


\begin{alltt}
\{
  "job":"https://staging.amusewiki.org/tasks/status/31848",
  "url":"https://staging.amusewiki.org/special/my-special"
\}
\end{alltt}

\subsection{Parameters}

\subsubsection{Mandatory}


\begin{description}

\item[{\texttt{\_\_auth\_user}}] 
The username


\item[{\texttt{\_\_auth\_pass}}] 
The password


\item[{\texttt{title}}] 
The text title


\item[{\texttt{textbody}}] 
The HTML body


\end{description}
\subsubsection{Optional}


They are the very same parameters you can find in the
\texttt{/action/text/new} form.


\begin{description}

\item[{\texttt{subtitle}   }] 
Text subtitle


\item[{\texttt{author}     }] 
Text author


\item[{\texttt{notes}      }] 
HTML string with the notes


\item[{\texttt{teaser}     }] 
HTML string with the teaser


\item[{\texttt{LISTtitle}  }] 
Text for indexing


\item[{\texttt{SORTauthors}}] 
List of authors, comma or semicolon separated list


\item[{\texttt{SORTtopics} }] 
List of topics, comma or semicolon separated list


\item[{\texttt{date}       }] 
Date of the text


\item[{\texttt{uid}        }] 
Unique identifier (for multilanguage support)


\item[{\texttt{cat}        }] 
Fixed category list (separated by space)


\item[{\texttt{slides}     }] 
Boolean if slides are required (if the site sets that)


\item[{\texttt{source}     }] 
String with the source notes


\item[{\texttt{lang}       }] 
ISO code language (e.g. \texttt{en})


\item[{\texttt{pubdate}    }] 
Publication date


\end{description}
\section{Non-interactive editing}


Editing pages via API works the same way. However, a word of caution:
while using the web interface you get warned if there are pending
revisions, via API you unconditionally spawn a revision and publish it.
If by chance you have other users editing it, they will get conflicts,
have your or their changes overwritten.


\begin{alltt}
curl -F \_\_auth\_user=\$username \textbackslash{}
     -F \_\_auth\_pass=\$password \textbackslash{}
     -F body='<test.muse' \textbackslash{}
     -F message='Edit my special via api' \textbackslash{}
     https://staging.amusewiki.org/remote/edit/special/my-special
\end{alltt}


Or:


\begin{alltt}
curl -F \_\_auth\_user=\$username \textbackslash{}
     -F \_\_auth\_pass=\$password \textbackslash{}
     -F body='<test.muse' \textbackslash{}
     -F message='Edit my library via api' \textbackslash{}
     https://staging.amusewiki.org/remote/edit/library/my-library
\end{alltt}


Response:


\begin{alltt}
\{
  "job":"https://staging.amusewiki.org/tasks/status/31864",
  "url":"https://staging.amusewiki.org/special/my-special"
\}
\end{alltt}


or an error:


\begin{alltt}
\{"error":"This text cannot be edited"\}
\end{alltt}


As shown above, the endpoint in \texttt{/remote/edit/} with the full URI of
the text appended.

\subsection{Parameters}

\subsubsection{Mandatory}


\begin{description}

\item[{\texttt{\_\_auth\_user}}] 
The username


\item[{\texttt{\_\_auth\_pass}}] 
The password


\item[{\texttt{message}}] 
A commit message to explain what you did


\item[{\texttt{body}}] 
The full body in Muse format (in the examples above, \texttt{curl} is reading from a file)


\end{description}
\subsubsection{Optional}


The are the same options you can find in the editing page. Use a value
of 1 to activate them.


\begin{description}

\item[{\texttt{fix\_links}}] 
Make all links active


\item[{\texttt{fix\_typography}}] 
Smart quotes


\item[{\texttt{fix\_nbsp remove\_nbsp}}] 
Unconditionally remove all the invisible non-breaking spaces in the text


\item[{\texttt{show\_nbsp}}] 
Make all non-breaking spaces explicit and visible as \textasciitilde{}\textasciitilde{}


\item[{\texttt{fix\_footnotes}}] 
Rearrange the footnotes


\end{description}

\begin{alltt}
curl -F \_\_auth\_user=\$username \textbackslash{}
     -F \_\_auth\_pass=\$password \textbackslash{}
     -F body='<test.muse' \textbackslash{}
     -F fix\_footnotes=1 \textbackslash{}
     -F message='Edit my library via api' \textbackslash{}
     https://staging.amusewiki.org/remote/edit/library/my-library
\end{alltt}


Beware that some filters, like the footnote filter, may trigger errors
which are returned to the caller, e.g.:


\begin{alltt}
\{
  "error": \{
    "references": 1,
    "references\_found": "[2]",
    "footnotes": 0,
    "footnotes\_found": "",
    "differences": "@@ -0,0 +1 @@\textbackslash{}n+[2]\textbackslash{}n"
  \}
\}
\end{alltt}







% begin final page

\clearpage



% new page for the colophon

\thispagestyle{empty}

\begin{center}





\bigskip
\includegraphics[width=0.25\textwidth]{logo-amw.pdf}
\bigskip

\end{center}

\strut

\vfill

\begin{center}




Integration with external sites






\bigskip



   

       

       

       

       

       
   



\bigskip
\textbf{amusewiki.org}


\end{center}

% end final page with colophon


\end{document}


% No format ID passed.



