Nomnoml: diagramas UML desenhados com sintaxe de texto

• Ferramenta para escrever diagramas UML como código: ao editar a sintaxe de texto à esquerda, o diagrama renderizado muda junto
• Suporta vários elementos de diagrama e notações de relacionamento, como classes, componentes, fluxogramas, casos de uso, banco de dados e tabelas
• As edições são salvas no localStorage do navegador e podem permanecer na próxima visita, mas o salvamento não é garantido
• É possível mover e ampliar/reduzir o canvas com arraste e rolagem na área do terço direito, e o editor oferece suporte parcial ao mapeamento de teclas do Sublime Text
• Com diretivas # e diretivas de estilo . é possível ajustar fonte, direção, espaçamento, cores, formato das linhas e estilos de classificadores personalizados

---

Diagramas montados com sintaxe de texto

• Nomnoml é uma ferramenta para escrever e renderizar diagramas com sintaxe baseada em texto

• Notação de relacionamentos

  • É possível usar association, dependency, generalization, implementation, composition, aggregation, ball and socket, note, hidden etc.
  • Ex.: [Car]->[Engine]
  • Ex.: [Car] +-> 0..* [RustPatch]
  • Ex.: [Car]o->[Manufacturer]
  • Ex.: [Car]<:-[Pickup]

• Classificadores suportados

  • Em diagramas de classe, além da classe padrão, há suporte a abstract, instance, reference, package, frame
  • Em diagramas de componente, é possível usar a notação socket e lollipop
  • Os elementos de fluxograma incluem start, end, state, choice, sync, input, sender, receiver, transceiver
  • Diagramas de caso de uso suportam actor e usecase
  • Outros elementos disponíveis são note, label, hidden, database, pipe, table
    • Um exemplo de tabela tem a forma [<table>Fruits| Apples | 17 || Oranges | 4711]

Edição, diretivas e estilos

• // no início da linha é tratado como comentário
  • // no meio da linha, como em [not //commented], não é comentário
• Ao usar a propriedade id, é possível transformar dois nós com o mesmo nome exibido em nós diferentes
  • Ex.: [<actor id=a>User], [<actor id=b>User], [a] -- [b]

• Ajuste de layout e renderização com diretivas #

  • #import: filename
  • #direction: down | right
  • #edges: hard | rounded
  • #background: transparent
  • #font, #fontSize, #spacing, #padding, #stroke, #fill, #zoom
  • #ranker: network-simplex | tight-tree | longest-path

• Definição de estilos de classificadores com diretivas .

  • Ex.: #.box: fill=#8f8 dashed
  • Ex.: #.blob: visual=ellipse title=bold
  • É possível usar chaves/valores como fill, stroke, align, direction, visual
  • Também é possível definir o estilo do texto do título e do corpo, como em title=left,italic,bold e body=center,italic,bold
  • Os exemplos de uso incluem troca de fonte, layout compacto, criação de tabelas, estilos personalizados e divisão em vários arquivos
  • A divisão em vários arquivos usa o formato #import: blobby_styles
  • As alterações na tela de edição são salvas no localStorage do navegador, e o canvas pode ser movido e ampliado/reduzido com arraste e rolagem na área do terço direito
  • O editor oferece suporte parcial ao mapeamento de teclas do Sublime Text, e o Nomnoml está hospedado no GitHub

[GN⁺]

Opiniões do Hacker News

• Link do GitHub: https://github.com/skanaar/nomnoml

• No começo achei bem confuso, e só entendi depois que encontrei o botão about
  Talvez eu tenha tido a sorte de viver sem reconhecer UML de cara. No início, achei que fosse uma explicação de alguma sintaxe falsa em fala de pirata

  • Um jeito de reconhecer UML é a quantidade enorme de estilos de seta que ninguém consegue lembrar. Tenho uns 90% de certeza de que esse é o principal motivo de UML nunca ter se popularizado de vez
    Acho muito melhor uma abordagem como esta, que de vez em quando reconhece o fato de que ninguém vai decorar 10 tipos de seta para ler um diagrama UML: https://buck2.build/docs/concepts/concept_map/
  • Tecnicamente, acho que isto não é UML padrão
    Mas muitas ferramentas que usam o termo “UML” também não são, e na prática muitas vezes precisamos de algo menos preciso e menos verboso do que UML teórico

• Antigamente havia um site open source que comparava ferramentas de conversão de “texto para diagrama”: https://text-to-diagram.com/
  nomnoml não está na lista

  • O site foi feito pelos mantenedores do D2, então pode haver viés, mas ainda acho que a sintaxe do D2 é a mais amigável dessa categoria, incluindo nomnoml
    [1]: https://d2lang.com/

• Gosto do Nomnoml. Recentemente tenho usado em um projeto de gerenciamento de conhecimento pessoal (PKM) baseado em navegador em que estou trabalhando, para visualizar uma estrutura hierárquica de tags
  O layout costuma sair bem limpo. Exemplo: https://imgbox.com/9A1mDyNv

• A parte mobile parece precisar de ajustes. Abri no celular e o diagrama foi desenhado por cima do editor, então não dava para usar o editor

  • Isso é apenas o comportamento do site de demonstração do nomnoml. A configuração serve para mostrar que, ao editar o texto, o diagrama UML renderizado muda em tempo real
    A biblioteca JavaScript por baixo pode renderizar diretamente em um canvas HTML ou para SVG em um programa Node.js e, se quiser, também pode ser executada pela linha de comando

• Já criei algumas ferramentas com nomnoml no passado, incluindo grafos de fluxo de controle e grafos de dependência de código assembly de GPU
  Gostei muito, mas achei uma pena não haver uma forma confiável de forçar certos elementos a ficarem próximos entre si. Em diagramas muito grandes, às vezes ele faz escolhas ruins e fica bagunçado
  Mesmo a documentação não sendo completa, o código é bem fácil de modificar, então consegui hackear tooltips ao passar o mouse e fazer certos blocos levarem a outros diagramas quando clicados. Sou grato por uma ferramenta tão boa ser open source

• Conseguir um bom layout depende demais da ordem das definições. Em diagramas grandes isso pode ficar difícil para o usuário resolver, mas em diagramas pequenos parece funcionar bem
  Por exemplo, se você escrever o mesmo exemplo dos piratas em outra ordem, ele continua válido, mas produz um layout feio

  • O problema dessas ferramentas é que, mesmo quando você consegue de algum jeito um bom layout na documentação, no momento em que adiciona, remove ou altera algo, precisa brigar com ele de novo
    Já experimentei alguns desses produtos de diagramas baseados em código sonhando com um mundo em que a documentação técnica, incluindo os diagramas, fizesse parte do código-fonte do projeto, mas era difícil conseguir layouts aceitáveis, especialmente para distribuição externa, e até mesmo para uso interno
    Essa frustração geralmente leva a dois resultados ruins: o diagrama fica ilegível ou deixa de ser mantido
    Para ser sincero, a ideia de fazer code review da documentação no check-in também é quase um mito. Diffs desse tipo de documento são muito difíceis de entender, e é praticamente impossível verificar de forma significativa se a documentação está correta sem renderizá-la e ver o resultado
    É o tipo de problema que eu realmente gostaria que desse certo, e talvez um dia vire um problema resolvido
  • Correção: achei que ele fosse disposto de cima para baixo, mas não era isso; a ordem é determinada de outra forma
    Comparando a tabela Pirate original com a tabela Pirate do comentário pai, a parte de cima e de baixo ficam invertidas. Mesmo definindo beard e parrot primeiro na ordem de exibição desejada, ainda sai invertido
  • Precisamos de outra ferramenta que otimize a permutação das sentenças para minimizar sobreposições no diagrama resultante
  • Esse exemplo dos piratas não ajuda muito a entender. Fico me perguntando se há alguma forma de organizar essas palavras embaralhadas de modo que façam sentido

• Bonito, e parece muito melhor do que diagramas de classe do PlantUML
  [0]: https://plantuml.com/class-diagram

  • Talvez. Mas, em vez de criar mais um padrão fragmentado, fico pensando se não daria para deixar mais bonito o estilo padrão de um padrão que já é bastante suportado
  • O PlantUML dá suporte a diagramas de sequência, que são um dos tipos de diagrama que mais uso. Infelizmente, o nomnoml não oferece suporte a eles

• Me lembra graphviz