# Seeking Testers For A Simple Port



## Michael-Sanders (Feb 3, 2013)

Hi folks.

I've built a FreeBSD port, and I was hoping to get some feedback that it does in fact build/install/deinstall properly on a variety of FreeBSD systems (I've tested this very thing on 3 other systems several times as per the porter's handbook without any issues).

If approved, it ought to be listed under textproc/topic. This utility features an extremely simple markup language for parsing plain-text databases using topic markup. Its only dependency is glibc, and builds/installs a single binary, and a single man page, nothing more.

Here's a description:

_'TOPIC markup provides a minimal context for plain text databases that can be read/modified by most text editors, and easily parsed as well.

Uses include: knowledge-bases, glossaries, apropos, notes... Portable C sources will compile under virtually any environment.'_

To test the port, you'll first need to download the port distribution tarball (contains: Makfile/distinfo/pkg-descr/pkg-plist) located at:

www.topcat.hypermart.net/code/topic-port-make.tar.gz [718 bytes]

Then unpack the archive to /usr/ports/textproc/topic

To compile/install topic, as root invoke:


```
# cd /usr/ports/textproc/topic && make install clean
```

The port should now be installed. Depending on your shell, you may also need to type:


```
# rehash
```

To self-test topic type:


```
# topic -m | topic -i
```

Its output should exactly match the following:


```
TAG: 1, SYNOPSIS
TAG: 2, KEY CONCEPTS
TAG: 3, TAGS
TAG: 4, BLOCKS
TAG: 5, LINES
TAG: 6, ASSOCIATIONS
TAG: 7, Apples, Fruit
TAG: 8, Oranges, Fruit
TAG: 9, PARSING
TAG: 10, GLOSSARY, i, ii, iii, iv, v, vi
TAG: 11, HEX TABLE
TAG: 12, LEGALESE
TAG: 13, COLOPHON
```

To read more about topic, simply read its man page:


```
man topic
```

To study and better understand the topic markup specification, please view this document (it explains all you'll need to know about creating your own topic database, and no worries its super easy).

To deinstall (remove) topic, as root from the /usr/ports/textproc/topic directory type:


```
# make deinstall
```

Thanks for any feedback, I appreciate it.


----------



## bkouhi (Feb 3, 2013)

Congratulations! I've tested it, everything seems Ok. This is output of that command:


```
# topic -m | topic -i
TAG: 1, SYNOPSIS
TAG: 2, KEY CONCEPTS
TAG: 3, TAGS
TAG: 4, BLOCKS
TAG: 5, LINES
TAG: 6, ASSOCIATIONS
TAG: 7, Apples, Fruit
TAG: 8, Oranges, Fruit
TAG: 9, PARSING
TAG: 10, GLOSSARY, i, ii, iii, iv, v, vi
TAG: 11, HEX TABLE
TAG: 12, LEGALESE
TAG: 13, COLOPHON
```


----------



## Michael-Sanders (Feb 3, 2013)

I can exhale... =) Many thanks bkouhi. It surely is humbling, even intimidating to post a port... (worried & fretting that a guru, wizard, or unix-beard rips my face off if I made a mistake on their personal system).

Anyhow, again I appreciate your feedback.


----------



## jrm@ (Feb 3, 2013)

It works for me.


```
cd /usr/ports/textproc/topic && portlint
FATAL: Makefile: extra item "MAINTAINER" placed in the PORTNAME section.
FATAL: Makefile: extra item "COMMENT" placed in the PORTNAME section.
FATAL: Makefile: extra item "MAN1" placed in the PORTNAME section.
FATAL: Makefile: extra item "MANCOMPRESSED" placed in the PORTNAME section.
WARN: Makefile: only one MASTER_SITE configured.  Consider adding additional mirrors.
FATAL: Makefile: extra item "do-install:" placed in the MAINTAINER section.
FATAL: Makefile: extra item "   ${INSTALL_PROGRAM} ${WRKSRC}/topic ${PREFIX}/bin/topic" placed in the MAINTAINER section.
FATAL: Makefile: extra item "   ${INSTALL_MAN} ${WRKSRC}/topic.1 ${PREFIX}/man/man1/topic.1" placed in the MAINTAINER section.
WARN: Makefile: COMMENT is set externally to this port's Makefile, but this port is not configured as a slave port.
7 fatal errors and 2 warnings found.
```

This slightly modified makefile gives just the warning about one master site.


```
# $FreeBSD$

PORTNAME=		topic
PORTVERSION=	1.02
CATEGORIES=		textproc
MASTER_SITES=	http://topcat.hypermart.net/code/

MAINTAINER=		ports@FreeBSD.org
COMMENT=		Topic markup parser

MAN1=			topic.1
MANCOMPRESSED=	no

do-install:
	${INSTALL_PROGRAM} ${WRKSRC}/topic ${PREFIX}/bin/topic
	${INSTALL_MAN} ${WRKSRC}/topic.1 ${PREFIX}/man/man1/topic.1

.include <bsd.port.mk>
```


----------



## Michael-Sanders (Feb 3, 2013)

Ah... I see. So you're inferring that according to portlint each directive has a predefined line number?


----------



## jrm@ (Feb 3, 2013)

No, just a few newlines to separate sections.


----------



## wblock@ (Feb 3, 2013)

Set yourself to be the MAINTAINER.  Just a single tab is needed before variable values:

```
# $FreeBSD$

PORTNAME=	topic
PORTVERSION=	1.02
CATEGORIES=	textproc
MASTER_SITES=	http://topcat.hypermart.net/code/

MAINTAINER=	me@example.org
COMMENT=	Topic markup parser

MAN1=		topic.1
MANCOMPRESSED=	no

do-install:
	${INSTALL_PROGRAM} ${WRKSRC}/topic ${PREFIX}/bin/topic
	${INSTALL_MAN} ${WRKSRC}/topic.1 ${PREFIX}/man/man1/topic.1

.include <bsd.port.mk>
```

Looks good.  Thanks for adding to the ports collection!


----------



## Michael-Sanders (Feb 3, 2013)

Okay. Edited as per your suggestions to placate portlint & re-uploaded (still learning the in's & out's, mighty grateful for the tips jrm).


----------



## Michael-Sanders (Feb 3, 2013)

wblock@ said:
			
		

> Set yourself to be the MAINTAINER



Yes sir, will do. A question in fact I was about to ask (examples seemed ambiguous to me on that point).


----------



## jrm@ (Feb 3, 2013)

You're welcome.  

As @wblock said, thanks for porting and note the tabs.


----------



## Michael-Sanders (Feb 3, 2013)

Final question (I hope)...

If I've already submitted the port for consideration via send-pr -a topic.shar, yet sill need to correct the MAINTAINER line in the port's Makefile. How does one rectify that situation? Simply wait until & if its approved or... I'm not sure honestly.


----------



## jrm@ (Feb 3, 2013)

Michael-Sanders said:
			
		

> Final question (I hope)...
> 
> If I've already submitted the port for consideration via send-pr -a topic.shar, yet sill need to correct the MAINTAINER line in the port's Makefile. How does one rectify that situation? Simple wait until & if its approved or... I'm not sure honestly.



You could upload a new .shar using the web interface.  You could also just append a followup telling whomever deals with the port submission about the changes.


----------



## Michael-Sanders (Feb 3, 2013)

Okay then, I'll get right on that (web interface) & quite things down now.


----------



## wblock@ (Feb 3, 2013)

New versions can be submitted as a followup to the original PR while it's still open.  The ports guys on IRC (EFnet, #bsdports) are very active and usually more than willing to offer suggestions.


----------



## culot@ (Feb 5, 2013)

Hi Michael,

Thanks for this submission 
I took the PR myself and ran some tests. I wanted to suggest you a few minor tweaks to your ports:


MANCOMPRESSED is not necessary
pkg-plist entry could be moved to Makefile's PLIST_FILES
MANPREFIX should be used to install manpage

Regarding the first point actually the MANCOMPRESSED variable is already set to "no" in your case even if you do not specify it in the Makefile. As stated in Porter's Handbook (section 5.10):



> MANCOMPRESSED is automatically set to yes if USE_IMAKE is set and NO_INSTALL_MANPAGES is not set, and to no otherwise. You do not have to explicitly define it unless the default is not suitable for your port.



You can check this by issuing the following command in the port directory and checking it returns "no" even if you do not specify MANCOMPRESSED in the Makefile:

[cmd=]make -V MANCOMPRESSED[/cmd]

For the second point, it is common practice to avoid using pkg-plist files when there are not that many entries in it, as stated in Porter's Handbook section 3.2.2:



> There is only one case when pkg-plist can be omitted from a port. If the port installs just a handful of files, and perhaps directories, the files and directories may be listed in the variables PLIST_FILES and PLIST_DIRS, respectively, within the port's Makefile



So I just removed the pkg-plist file and added 
	
	



```
PLIST_FILES=   bin/${PORTNAME}
```
 in the Makefile. Also note that I replaced "topic" by "${PORTNAME}" wherever possible.

So here is an updated shar based on the above remarks:


```
# This is a shell archive.  Save it in a file, remove anything before
# this line, and then unpack it by entering "sh file".  Note, it may
# create directories; files and directories will be owned by you and
# have default permissions.
#
# This archive contains:
#
#       topic
#       topic/Makefile
#       topic/distinfo
#       topic/pkg-descr
#
echo c - topic
mkdir -p topic > /dev/null 2>&1
echo x - topic/Makefile
sed 's/^X//' >topic/Makefile << '50be4062945024160078a562eded2415'
X# $FreeBSD$
X
XPORTNAME=      topic
XPORTVERSION=   1.02
XCATEGORIES=    textproc
XMASTER_SITES=  [url]http://topcat.hypermart.net/code/[/url]
X
XMAINTAINER=    [email]mike@topcat.hypermart.net[/email]
XCOMMENT=       Topic markup parser
X
XPLIST_FILES=   bin/${PORTNAME}
XMAN1=          ${PORTNAME}.1
X
Xdo-install:
X       ${INSTALL_PROGRAM} ${WRKSRC}/${PORTNAME} ${PREFIX}/bin/${PORTNAME}
X       ${INSTALL_MAN} ${WRKSRC}/${PORTNAME}.1 ${MANPREFIX}/man/man1/${PORTNAME}.1
X
X.include <bsd.port.mk>
50be4062945024160078a562eded2415
echo x - topic/distinfo
sed 's/^X//' >topic/distinfo << '75f7a442c767bea6a035a94239998b72'
XSHA256 (topic-1.02.tar.gz) = 1150cca9b447fbf3cf79305574bc92c1c751a73727735e6f8c49b9171e952ffb
XSIZE (topic-1.02.tar.gz) = 6028
75f7a442c767bea6a035a94239998b72
echo x - topic/pkg-descr
sed 's/^X//' >topic/pkg-descr << '62f6ce1326a638fa58422162e3a80f58'
XTOPIC markup provides a minimal context for plain text databases that
Xcan be read/modified by most text editors, and easily parsed as well.
X
XWWW: [url]http://topcat.hypermart.net/topic.html[/url]
62f6ce1326a638fa58422162e3a80f58
exit
```

Let me know if you agree with the above changes so I can commit your new port. Thanks again for this submission Michael!

Cheers,
Frederic


----------



## Michael-Sanders (Feb 5, 2013)

Hi Frederic.

Yes I agree with your changes, & thanks for the updated shar. I appreciate that you took the time to explain the ports Makefile rationale.


----------



## culot@ (Feb 6, 2013)

Hi again Michael,

I just committed your new port: http://svnweb.freebsd.org/ports?view=revision&revision=311753.

Moreover, I added you to the official list of FreeBSD contributors: http://svnweb.freebsd.org/doc?view=revision&revision=40898. Hence your name will appear (after the document is regenerated) in the FreeBSD handbook in this section: http://www.freebsd.org/doc/en_US.ISO8859-1/articles/contributors/article.html#contrib-additional.

Thanks again!
Frederic


----------

