JIRA issue 中的标记语言(Textile)

_匿蟒_

简介

昨天忽然发现,公司用的JIRA issue中,竟然是用Textile作为标记语言。

这也是一种轻量级标记语言,能力比流行的Markdown更强大,因为设计目的不同。Markdown是为了写作而设计,而Textile是为了更快地写HTML。
但是在JIRA上却有诸多限制,也许是为了某种程度的简单,而删减掉了吧。

Textile 语法参考

第一个是中文,其它全是英文。

上述语法介绍,在 JIRA 上并非全部有效。

在 JIRA 上的有效语法

标题

  • h1. 标题一

  • h2. 标题二

  • h3. 标题三

  • h4. 标题四

  • h5. 标题五

  • h6. 标题六

字体

显示 输入
黑体 *黑体*
斜体 _斜体_
删除线 -删除线-
下划线 +下划线+
下标sub 下标 ~sub~
上标sup 上标 ^sup^

所有这些标记基本都要保证*-这些字符不在一个英文单词或中文句子的中间,否则无效。可以在外面再加一层空格。

引用

bq. 这是引用,不能换行。

这是引用,不能换行。

其实bq. 能用已经让我很诧异了,因为其它b开头的标记都挂了。

Textile通常是用p. 来区分段落的,而在JIRA上禁用它后用的是换行符,因此bq. 只能作用与一行。

图片

用两个!包裹起来。

!/path/to/image!
!https://camo.githubusercontent.com/313d034adacb3426c4347317ce9047c23161e6b2/68747470733a2f2f646c2e64726f70626f7875736572636f6e74656e742e636f6d2f752f3637333231342f74657874696c652d776f72646d61726b2d737065632e706e67!

textile

不支持各种杂七杂八的Textile图片语法,例如:

!/path/to/image 10w 20h!
!/path/to/image 20%x40%!
!/path/to/image 20%!
!/path/to/image (Alt text)!

这些统统不支持!

无序列表

Textile是只能用*,这里JIRA上可以用-

* 无序列表一
* 无序列表二
** 无序列表缩进一次
*** 无序列表缩进二次
** 无序列表缩进一次
* 无序列表三
  • 无序列表一

  • 无序列表二

    • 无序列表缩进一次

      • 无序列表缩进二次

    • 无序列表缩进一次

  • 无序列表三

有序列表

有序列表不用标序。

# 有序列表一
# 有序列表二
## 有序列表缩进一次
### 有序列表缩进二次
## 有序列表缩进一次
# 有序列表三
  1. 有序列表一

  2. 有序列表二

    1. 有序列表缩进一次

      1. 有序列表缩进二次

    2. 有序列表缩进一次

  3. 有序列表三

表格

| First name | Family name |
| Stephen    | Hawking     |
| Steve      | Jobs        |
First name Family name
Stephen Hawking
Steve Jobs

不支持各种杂七杂八的表格语法。

链接

支持显式链接、邮箱,例如:

https://en.wikipedia.org/wiki/Textile_(markup_language)
mail@company.com

直接可得:

https://en.wikipedia.org/wiki/Textile_(markup_language)
mail@company.com

不支持其它任何形式的隐式链接。

也支持 JIRA issue ID 号自动转换为链接。

代码

基本上可以说不支持插入代码,因为无论是内联代码@inline@、还是代码块bc. code block,都不支持。
但是利用穷举法,竟然发现了一个类似代码块的东西。

|monospace test|||bold monospace text||,竟然可以得到两种被线框起来的文字,前者是白底,后者是灰底。

而代码块,或者说一种类似代码块的东西,只能以|的方式给出。|必须在行首(也就是说不能假装内联代码),后面可以空格,不能空行,必须跟着非空字符。最后收尾的|可以去掉。大括号必须转义,空格缩进无效。

|#include <stdio.h>
int main(void)
\{
 printf("Hello world!");
 return 0;
\}|

不仅需要转义大括号,而且没有缩进!

而如果用||,结果更有喜感:

用code||/code的结果……

这不是Textile的语法。而且,这种效果简直不能忍!

看来给程序员进行软件项目管理的JIRA,不适合写代码块。

不支持

  • 不支持脚注

  • 不支持对齐

  • 不支持缩进

  • 不支持p.

  • 不支持pre.或pre..

  • 不支持特殊字符(c)(tm)等。

  • 不支持HTML插入

编辑器

我一般不用Textile,所以没有研究过专门的编辑器。

在JIRA上,通过Firefox的Vimperator的Ctrl+i,把编辑区转到Vim中编辑。

Plugin 'timcharper/textile.vim'

通过上述插件,可以实现语法高亮,比大多数Vim的Markdown插件好得多。
虽然也支持预览,但是很遗憾我的工作平台是Windows,没有配置Ruby环境。

结语

我不知道为什么JIRA用的是Textile这种标记语言,但总体来说,它的一些语法细节还是比流行的Markdown更合适做工作内容交流。比如多重列表,在不能输入TAB的网页编辑区内,它就非常合适。
如果没有被删减、或者至少保留Code的语法,就更好了。


如果说前面都是一些可能会在工作中用到的技术记录,那么后面就是感慨了。

我在这家公司,用这个系统已经有一年半了,从来没有人提起过、使用过其Textile功能!每一个issue的页面,哪怕是会被自动导入每一个新项目的CR,也都是纯文本的渣排版

虽然Textile的确是一种难以“误触”的标记语言,没有哪个特别的语法是和普通输入混淆的。自动超链接由于太常见,所以被忽略了。我如果没有发现其自动去除行首空字符、自动把我贴上去的一段Java块注释解析成列表,我也不会发现这里竟然有一个标记语言!然后,通过三个试探出的已知语法,黑体、斜体、列表,去所有轻量级标记语言(Lightweight Markup Language)里,找到了唯一的匹配——Textile。

目前,似乎在我以外都没有其它任何人发现、使用这个功能,让海量的issue能够摆脱纯文本的呈现方式,提高工作效率。除了文本内容以外,我最不能忍的是工作环境中的图片呈现。
很多issue内容,是以图片为第一内容的,比如界面上出现了一个显示问题。而现在所有的issue图片,都作为附件的方式附在上面,打开前要手动下载!另外还有一种图片,需要跳转到另一个页面观看,但少有人用。除了因为上传时稍微麻烦些,更重要的是,这种查看体验和下载也没什么区别。
如果换成Textile的图片链接,显然可以大幅提高工作效率。

Textile,或者任何一种标记语言,对程序员来说都不算什么高门槛,没人发现、没人使用,更重要的还是一种技术的钝感。对新技术缺乏渴望,对工作相关的事物全不在意,对提高自己和同事的工作效率毫无兴趣。
而那些系统的维护者,对自己维护的JIRA系统不做任何推广。新开发的小功能一封邮件了事,JIRA本身就有的功能也毫不传播。我刚进公司、不知JIRA为何物时,竟然没有任何培训!直到现在,我们的JIRA上仍然充斥着不知道JIRA为何物的人,随意地改状态、写comment、骂战……
文案、issue的撰写者,依旧满足于在JIRA上用纯文本加上各种自定义格式来表达想法、不行就用doc文件在各个地方传来传去,对既有的或新兴的其它高效方式漠不关心。

在这样的环境中,一年的工作经验可以用十年。

我不得不考虑……


话说,碰巧看到本文的诸位,你们如果也用JIRA,可曾发现你们的issue中的标记语言,是否也是缩减版Textile

阅读 9.2k

匿蟒的专栏
计算机、编程领域的技术博客,记录我个人从零单排技术天梯的进程。

刚入职场,底层码农。

66 声望
0 粉丝
0 条评论
你知道吗?

刚入职场,底层码农。

66 声望
0 粉丝
宣传栏