\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#467: Move TIP Collection to Fossil}
\date{March 14, 2017}
\author{Mark Janssen}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#467}&\textbf{Move TIP Collection to Fossil}\\\hline
Author&

Mark Janssen \tipmail{mpc.janssen}{gmail.com}
\\
Created&Tuesday, \(\text{14}^{\text{th}}\) March 2017\\
Type&Process\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.5 $\\
Keywords&migration\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

The Tcl TIP collection shall be moved to Fossil and the process of managing TIPs shall use Fossil as much as possible. The TIP format will be changed from a TIP-specific form to Markdown.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Triggered by some people having issues with changing content on current TIP website and discussion on the \#tcl chat, I have experimented with fossil as a medium to host the Tcl TIP collection.

The current TIP storage and handling requires a lot of scripts that need to be maintained by the TCT and it is less open than it could be. There are also advantages to switching to Fossil in place of CVS.
\begin{itemize}
\item{}
Fossil has embedded Markdown rendering.
\item{}
Fossil is already used to manage the Tcl and Tk sources.
\item{}
TIP discussion and CFVs can be done and tracked using fossil tickets.
\item{}
Fossil events could also track CFV's and Vote results
\item{}
CVS is extremely vulnerable to problems with system administration on a single host. With a fossil-based system, it is much simpler to have multiple repositories.
\end{itemize}

Besides Fossil supporting Markdown out of the box, markdown is also better option for the future than the current format. The value of making up your own plain text format in this age is debatable (especially for the TIP requirements). Markdown has widely available options to convert to other formats without any need for the community to maintain the converters, and supports key extra features such as embedded images (which are important for some Tk TIPs, and never worked particularly well with the old TIP format).

\section{Specification}

Proposed URL for the new repository will be \url{http://core.tcl.tk/tips}

\subsection{Backwards compatibility}
\begin{itemize}
\item{}
\textit{tip.tcl.tk/\tiplangle{}NUM\tiprangle{}.html} should still show a rendered result. This could be redirected to \textit{core.tcl.tk/tips/doc/trunk/tip/\tiplangle{}NUM\tiprangle{}.md}
\item{}
\textit{tip.tcl.tk} offers several converted formats (XML, *roff, ...). The fossil option will be to use the \textit{core.tcl.tk/tips/file/tip/\tiplangle{}NUM\tiprangle{}.md?download} URL to get the raw Markdown downloads. For getting the other options one could convert the markdown source file using something like pandoc.
\item{}
E-mail address are not hidden in the source and in the rendered result. If e-mail addresses need to be hidden there are two options
\end{itemize}
\begin{enumerate}
\item{}
Remove mails from source.
\setcounter{enumi}{1}
\item{}
Hide e-mails in fossil.
\setcounter{enumi}{2}
\item{}
Hide e-mails in the webhost.
\end{enumerate}

 Option 2. doesn't help much as the mails are still online in the raw markdown files. Option 1. loses information. Suggested is to leave the addresses untouched. 

\subsection{Process}

TBD

\subsection{TIP Format}

The Markdown tip format has one extension to standard Markdown:

Any TIP.md file will have a mandatory preamble starting with the title (for fossil rendering) and ending with a `-{}-{}-{}-{}-{}-` on a single line. Between these parts there is tab indented meta information about the tip. (Tab indented so it renders nicer in fossil, 4 spaces would also work)

Example from \cite{tip0}:
\begingroup\small\begin{verbatim}
# TIP 0: Tcl Core Team Basic Rules
    State:          Final
    Type:           Process
    Vote:           Done
    Post-History:
------
\end{verbatim}
\endgroup

\section{Implementation}
\begin{itemize}
\item{}
There is a proof of concept conversion (with CVS history) at \url{https://fossil.mpcjanssen.nl/tips}
\item{}
The scripts for the automatic conversion are at \url{https://fossil.mpcjanssen.nl/tip-migration}
\end{itemize}

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\begin{thebibliography}{TIP \#1}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#0]{tip0}
John Ousterhout,
\emph{Tcl Core Team Basic Rules},
on-line at \url{http://purl.org/tcl/tip/0.html}
\end{thebibliography}
\end{document}
